Unplayable Items

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

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

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.

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.

From here on unplayable items will be referred to as tokens. Here's a list of important token properties with respect to scripting:

1. 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.
2. 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.)
3. 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).
4. You can add a token remotely - i.e. to an actor not even in your cell, so long as it is a persistant ref.
5. 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.
6. 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.
7. Like spells, tokens can remove themselves or be removed from a calling script (very handy for instant or 1-time effects).

Creating an unplayable item

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 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.
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.
3. Uncheck the Playable option.
4. Attach/create your object script - your 'token effect'.

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

Token scripting (example)

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

ref target

Begin GameMode

; wait for player presence
if GetInSameCell player
  ; add items (or spells) to inventory and remove effect
  set target to GetContainer
  set type to 0.03*GetRandomPercent
  if type == 0
    target.AddItem MyItem01 1
  elseif type == 1
    target.AddItem MyItem02 5
  else
    target.AddSpell MySpell01
  endif
  RemoveMe
endif

End

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

short doOnce
; ...all other game mod variables

Begin GameMode

if doOnce
  Return
endif
set doOnce to 1

; this is a real unique ref in the std game (must be persistant and unique)
<InGameVendor1>.AddItem VendorToken 1
; another real unique ref to a second vendor
<InGameVendor2>.AddItem VendorToken 1

End

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.

Tokens on the player

(Very useful for OBSE key programming.)

Firstly a couple of notes:

1. Adding a token directly to the player will produce message spam.
2. 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.

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

; 1st frame - give stuff to shadow
MyShadow.AddItem MyToken 1
MyShadow.MoveTo player 0 0 -200
set frame to 1

End

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

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.

---

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

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

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. GuidoBot 15:00, 30 November 2006 (EST)