the Oblivion ConstructionSet Wiki

Difference between revisions of "Unplayable Items"

Unplayable Items (edit)

Revision as of 07:50, 24 June 2012

2,403 bytes added ,  07:50, 24 June 2012
Byline removed
imported>DragoonWraith
(revert because I am rather uncertain as to the accuracy of the edit. Would Elder please comment on them so we can understand why they're being made?)
imported>QQuix
(Byline removed)
 
(20 intermediate revisions by 9 users not shown)
Line 1: Line 1:
UNPLAYABLE ITEMS - AKA TOKENS by Guidobot


<!--Search words: tokens-->


===Introduction===
Ok, so you've probably heard about tokens all over the forums by now and are wondering "what are they" or "what's all the fuss about".
Ok, so you've probably heard about tokens all over the forums by now and are wondering "what are they" or "what's all the fuss about".


Well they are basically unplayable items that allow you to effectively reprogram any actor or even the player. In fact, despite their modest name, tokens are perhaps the most powerful tool that scripters have in the unextended CS. Tokens themselves are really almost that - i.e. they are an object that exists just to get the attached script to run on a target. What is actually important is the 'token effect'.
Well they are basically unplayable items that allow you to effectively re-program any actor or even the player.  
 
In fact, despite their modest name, tokens are perhaps the most powerful tool that scripters have in the unextended CS. Tokens themselves are really almost that - i.e. they are an object that exists just to get the attached script to run on a target. What is actually important is the 'token effect'.




To create a token:
===Properties of unplayable items===


In the default game, unplayable items such as the Emperor's Robe and the Imperial Palace Guard armour are not checked as "playable", preventing the player from taking these items from the person when they are killed.  Another example of armour which is flagged as unplayable is the armour belonging to Glenroy and Captain Renault in the original dungeon.  When Renault is killed, you can take her sword, but if you examine your corpse you are likely only to find a steel shortsword; you won't be able to take her Blades Armour, as this would unbalance the early game.


1) Choose any item in the game that has the Playable switch. These are  essentially clothing and weapons. Most favored choice seems to be a ring but it  really doesn't matter since it's 3D object will never see the light of day. In  fact a base model marked unplayable cannot be placed in game.
This is accomplished because unplayable items are not seen by the player, either in an actor's or player's inventory. Some other points about using an unplayable item on the player will be noted later. However, beyond this unplayable items behave pretty much like any other [non-persistant] item.


2) Copy your choice by saving with a new unique ID. You probably want to use the actual name as a comment as to what the token effect will do, etc.
From here on unplayable items will be referred to as tokens. Here's a list of important token properties with respect to scripting:


3) Uncheck the Playable option.
# Unlike standard items, the token is never seen in the target's/player's inventory. (This essentially makes up for the fact that inventory items cannot be disabled.) This feature can be useful in itself without any script attached. For example, you can tag an actor to see if you have already 'hit' them before.
# Tokens are always specific to the actor they are applied to, even if that actor was created by PlaceAtMe. In contrast, spells and abilities are added to the base model. (All [new] actor references of the same base model inherit these effects when they respawn.)
# Token variables are persistant, unlike scripted spells and abilities (which reset when the actor comes into scope (same cell) as the player, meaning any local variables are re-instantiated to 0).
# You can add a token remotely - i.e. to an actor not even in your cell, so long as it is a persistant ref.
# Token effect scripts are always active and the OnActivate block can be called when the actor is out-of-scope. This is not true of scripts on actors themselves.
# When [the marked actor is] in scope the GameMode block activates every frame. When out of scope the GameMode block triggers about every 30 seconds (?). Additionally it will always fire when the token is first added - meaning that you have an effective OnAdd method.
# Like spells, tokens can remove themselves or be removed from a calling script (very handy for instant or 1-time effects).


4) Attach/create your object script - your 'token effect'.
===Creating an unplayable item===
# Choose any item in the game that has the Playable switch. These are  essentially clothing and weapons. Most favored choice seems to be a 0-value ring.  Actors can equip an unplayable item, but if you use a ring it probably will not matter and making it worth 0 gold means they will not be inclinded to put it on.
# Copy your choice by saving with a new unique ID. You probably want to use the actual name as a comment as to what the token effect will do, etc.
# Uncheck the Playable option.
# Attach/create your object script - your 'token effect'.




To deploy a token on a target simply do the following command from any active script:
===Adding a token to an actor===
To deploy a token on a target actor simply do the following command from any active script:


  actor.AddItem MyToken 1
  actor.AddItem MyToken 1


So what's the point? Well it's mosty about what you can't do with other objects. Here's a list of important token properties:
1) Tokens are always specific to the actor they are applied to, even if that actor was created by PlaceAtMe. In contrast, spells and abilities are added to the base model. (All [new] actor references of the same base model inherit these effects when they respawn.)
2) Local variables are persistant. Scripted spell effects and abilities reset when the actor comes into scope (same cell) as the player, meaning any local variables are re-instantiated (to 0).
3) You can add a token remotely - i.e. to an actor not even in your cell, so long as it is a persistant ref.
4) Token effect scripts are always active and the OnActivate block can be called when the actor is out-of-scope. This is not true of scripts on actors themselves.
5) When [the marked actor is] in scope the GameMode block activates every frame. When out of scope the GameMode block triggers about every 30 seconds or whenever the player moves to a new cell. Additionally it will always fire when the token is first added - meaning that you have an effective OnAdd method.
6) Unlike standard items, the token is never seen in the target's/player's inventory. (This essentially makes up for the fact that inventory items cannot be disabled.)
7) Like spells, tokens can remove themselves or be removed from a calling script (very handy for instant or 1-time effects).


===Token scripting (example)===


Here's a very useful example. This token effect allows a merchant to initially have a particular spell in their inventory for sale. It is attached as the script to the token (you just made), called LoadSpellToken.
Here's a very useful example. This token effect allows a merchant to initially have one of a set of items in their inventory for sale the first time you visit. It is attached as the script to the token (you just made), called VendorToken.


  scn LoadSpellTokenEffect
  scn VendorTokenEffect
   
   
  ref target
  ref target
Line 51: Line 52:
  ; wait for player presence
  ; wait for player presence
  if GetInSameCell player
  if GetInSameCell player
; add spells to inventory and remove effect
  ; add items (or spells) to inventory and remove effect
   set target to GetContainer
   set target to GetContainer
   target.AddSpell MySpell01
   set type to 0.03*GetRandomPercent
   target.AddSpell MySpell02
  if type == 0
   target.AddSpell MySpell03
    target.AddItem MyItem01 1
   elseif type == 1
    target.AddItem MyItem02 5
   else
    target.AddSpell MySpell01
  endif
   RemoveMe
   RemoveMe
  endif
  endif
Line 61: Line 67:
  End
  End


To use this particular version I suggest a Quest script. There are other ways to do this but having a startup quest is a good idea for almost any mod involving scripting. Here a skeleton start up quest script, attached to quest ID MyStartupQuest:
To deploy this particular token effect I would suggest a quest script. There are other ways to do this but having a startup quest is a good idea for almost any mod involving scripting. Here is a skeleton start up quest script, attached to quest ID MyStartupQuest:


  scn MyStartupQuestScript
  scn MyStartupQuestScript
Line 76: Line 82:
   
   
  ; this is a real unique ref in the std game (must be persistant and unique)
  ; this is a real unique ref in the std game (must be persistant and unique)
  <InGameVendor1>.AddItem LoadSpellToken 1
  <InGameVendor1>.AddItem VendorToken 1
  ; another real unique ref to a second vendor
  ; another real unique ref to a second vendor
  <InGameVendor2>.AddItem LoadSpellToken 1
  <InGameVendor2>.AddItem VendorToken 1
   
   
  End
  End


Ok so what have we done here? Basically we've added spells to a particular vendor (or vendors) without ever modding any of the vanilla world - not even an activator/sensor placed next to the vendor!
Ok so what have we done here? Basically we've added items to a particular vendor (or vendors) without ever modding any of the vanilla world - not even an activator/sensor placed next to the vendor! You could use scripts that don't remove themselves the first time to do more complicated things, like maintain particular items in their inventory.




Note: In this example you may be able to do the AddSpell directly from the quest script. However, often you may need to add things multiple times or the particular commands may not work until the actor is in scope - hence the GetInSameCell conditional. Conditionals and global variables are often needed to ensure the timing of when token effects are triggered.
===Tokens on the player===


(Very useful for OBSE key programming.)


Aside: This works equally well for basic items, etc. However, much of the time you want to introduce a persistant scripted item in to the game. This is a bit more tricky since objects easily lose their scripts when being moved from 3D (the world) to 2D (an inventory/container). To do this firstly it is a good idea to have a room of your own to hold stuff, even if you can never get to this area from inside the game. The reason is by doing this you will never cause mod conflicts. You then need to:
Firstly a couple of notes:


(1) MyObject.MoveTo player  
# Adding a token directly to the player will produce message spam.
# Equipping a token on the player will make it appear that the token is equipped and will unequip an item of the same type, even though the item will not show up rendered or in the player's inventory. This can be useful BUT it will produce the usual item-equipped message spam.


(2) MyObject.Activate player
To give a player a token without causing any messages it is necessary to first add this to a container. However, since you cant be sure one exists near the player it is better to use your own persistant actor, or ''shadow'' (see [[Remote Activators]]).
 
scn ImporterScript
; This is a token script to get a token on the player!
; Called by simply doing MyShadow.AddItem ImporterToken 1
short frame
Begin GameMode
if frame == 1
  ; destroy command token
  RemoveMe
endif
   
   
(3) MyObject.RemoveMe <VendorHiddenContainer>.  
; 1st frame - give stuff to shadow
MyShadow.AddItem MyToken 1
MyShadow.MoveTo player 0 0 -200
set frame to 1
End


These 3 steps must be done in different (successive) frames. A (hidden) vendor container should be used. If you add directly to the vendor, 9/10 times you can bet that vendor will equip this item immediately - and not let go. (This is handy if you require the item to be pick-pocketed.)
This is a 1-time token script to add a token to the player using a shadow [actor]. The key thing here is that the shadow (hidden container) has to be in the player cell before you can get scripted items to remove themselves (silently) to the player. The first part of the token script would be:


Begin GameMode
if GetContainer == MyShadow
  RemoveMe player
  Return
endif
; actual token script goes below...
End


Tokens on the player: Very useful for OBSE key programming. It appears necessary to do this in 2 steps:
You can also use the shadow to bring in 3D items to the game. In this case  the '''Activate''' command would be used in place of the '''AddItem''' command (see [[Remote Activators]]). The important thing with these extended effects to watch for is ''timing''. In this case the commands that have to be handled carefully are MoveTo and RemoveMe.
 
(1) set tokenRef to player.AddItem MyPlayerToken 1


(2) tokenRef.Activate player


Again, to keep the attached token effect script, these command have to be done in different frames (use a counter). This is probably because of issues with OB expecting message spam for AddItem when added to the player. However, AddItem might work on it's own for you.
===Token abuse===
Because tokens are always active make sure you dont add them repeatedly or to almost very NPC you meet (in-game). Sometimes using a spell, ability or other method to get your active script going is more appropriate.


----


Token Abuse: Because tokens are always active make sure you dont add them repeatedly or to almost very NPC you meet (in-game). Sometimes using a spell, ability or other method to get your active script going is more appropriate.
===Comments===
'''Token Origin''': I wish I could say I invented tokens but I didn't. It appears they started out in thread discussions and were eventually put to use by early adopters such as Scruggs. Through thread discussions, I have only helped solidify our understanding of how and when to use them. [[User:GuidoBot|GuidoBot]]


'''Timing/persistance issues''': Tokens on actors that are engaged in major activity, e.g. fighting, may not get executed predictably every frame. [[User:GuidoBot|GuidoBot]] 16:09, 19 October 2006 (EDT)


Token Origin: I wish I could say I invented tokens but I didn't. It appears they started out in thread discussions and were eventually put to use by early adopters such as Shuggsywuggsy-the-ferret. Through thread discussions, I have only helped solidify our understanding of how and when to use them.
'''Tokens in Containers''': It turns out that '''Unequip <item> 1''' does not appear to work when applied to actors to force them to not equip an item, even if they have it currently equipped. This means you cannot ensure that any ''valuable'' wearable item added to merchant will be available for sale (although it should always be available for pick-pocketing). The safest way to ensure such items show up for sale is to add them to a nearby vendor chest instead. Fortunately, this is an example of where adding a (vendor) token to a container is more useful than adding it to an actor. [[User:GuidoBot|GuidoBot]] 15:00, 30 November 2006 (EST)


[[Category: Useful Code]]
[[Category: Useful Code]]
Anonymous user
Retrieved from "https://cs.uesp.net/wiki/Special:MobileDiff/32486...32507"