the Oblivion ConstructionSet Wiki

Difference between revisions of "Unplayable Items"

Unplayable Items (edit)

Revision as of 20:12, 18 October 2006

1,332 bytes added ,  20:12, 18 October 2006
Clean up, new info., re-write/simplification
imported>Elder
imported>GuidoBot
(Clean up, new info., re-write/simplification)
Line 1: Line 1:
UNPLAYABLE ITEMS - AKA TOKENS by Guidobot
==<font size=4>'''UNPLAYABLE ITEMS - AKA TOKENS'''</font>==




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".
By [[User:GuidoBot|GuidoBot]]


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'.


===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".


To create a token:
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'.


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.


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.
===Properties of unplayable items===
How unplayable items are actually intended to be used in the CS is unclear. They could be used to prevent the player taking items off of bodies but it is unclear whether any actors actually have such items in the standard game(?). Certainly a base object marked unplayable cannot be placed in game for the player (or actor) to pickup.


3) Uncheck the Playable option.


4) Attach/create your object script - your 'token effect'.
The only real point of unplayable items is that they 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.




To deploy a token on a target simply do the following command from any active script:
From here on unplayable items will be referred to as tokens. Here's a list of important token properties with respect to scripting:


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:
# 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.)
# 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).
# 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.
# 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.)
# Like spells, tokens can remove themselves or be removed from a calling script (very handy for instant or 1-time effects).




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.)
===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. It is unclear whether 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'.


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.
===Adding a token to an actor===
To deploy a token on a target actor simply do the following command from any active script:


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.
actor.AddItem MyToken 1


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.)
===Token Script Example===


7) Like spells, tokens can remove themselves or be removed from a calling script (very handy for instant or 1-time effects).
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 VendorTokenEffect
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.
 
  scn LoadSpellTokenEffect
   
   
  ref target
  ref target
Line 51: Line 57:
  ; 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*GetRanomdPercent
   target.AddSpell MySpell02
  if type == 0
   target.AddSpell MySpell03
    target.AddSpell MyItem01
   elseif type == 1
    target.AddSpell MyItem02
   else
    target.AddSpell MySpell01
  endif
   RemoveMe
   RemoveMe
  endif
  endif
Line 61: Line 72:
  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 87:
   
   
  ; 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.Activate 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.RemoveMe <VendorHiddenContainer>.  


These 2 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.)
To give a player a token without causing any messages it is necessary to first add this to a container. (See '''Discussion'''.) However, since you cant be sure one exist it is best 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
  ; 2nd frame - hide shadow and destroy command token
  MyShadow.Disable
  RemoveMe
endif
; 1st frame - give stuff to shadow
MyShadow.Enable
MyShadow.AddItem MyToken 1
MyShadow.MoveTo player 0 0 -5000
set frame to 1
End


Tokens on the player: Very useful for OBSE key programming. It appears necessary to do this in 2 steps:
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:


(1) set tokenRef to player.PlaceAtMe MyPlayerToken 1
Begin GameMode
 
(2) tokenRef.Activate player
if GetContainer == MyShadow
  RemoveMe player
  Return
endif
; actual token script goes below...
End


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.
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.




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.




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.
===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: JOG|JOG]] may have released the first tokens ever in his proofs-of-concept, [[User:JOG#The_Generous Giant_of_Tamriel|The Generous Giant of Tamriel]] and [[User:JOG#Dagger_Mould|Dagger Mould]].
[[User: JOG|JOG]] may have released the first tokens ever in his proofs-of-concept, [[User:JOG#The_Generous Giant_of_Tamriel|The Generous Giant of Tamriel]] and [[User:JOG#Dagger_Mould|Dagger Mould]].
Anonymous user
Retrieved from "https://cs.uesp.net/wiki/Special:MobileDiff/32492"