Primitives

In SimAntics, the opcode of an instruction can either refer to a built-in command, known as a **primitive**, or to a subroutine. The subroutines can be privates (belong to the object) semiglobals or globals. A global will have an opcode 256 to 4095, a private will have an opcode from 4096 to 8191 and a semiglobal will have an opcode >= 8192.

Instructions are executed synchronously within the thread until something yields the thread, an error is fired or the stack becomes empty. An example of this is the Animate Sim primitive. In the behaviours found in the game, this primitive often has a loopback on the false branch which points back to itself. The primitive returns true if the animation is complete and false if it is not. The false then loops back to the Animate Sim primitive to run the next frame. If this code was executed synchronously no animations would ever be observed. Therefore some primitives yield the thread.

You can think of primitives as having the following return values. GOTO\_TRUE, GOTO\_FALSE, ERROR, GOTO\_TRUE\_YIELD, GOTO\_FALSE\_YIELD.

The documentation below for primitives and their operands is correct for The Sims Online. The Sims 1 and 2 operands may be slightly different.

# The Sims Online Primitives

## 0 - Sleep

Changes the current virtual thread's state to sleeping. The number of ticks to sleep for is determined by a stack variable (local) specified by the operand.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Stack Var #

Unused

## 1 - Generic Sims Online Call

*Main article: Generic Sims Online Call*

This primitive is used to call upon game functions which are either not common enough to include as a primitive or very specialized with no parameters (eg. Disable/Enable Build/Buy).

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Call ID

Unknown (potentially any arguments?)

## 2 - Expression

Performs a logical or mathematical expression. The operator value describes what type of expression to perform and the other values determine the left and right hand side of the expression.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

LhsData

RhsData

IsSigned

Operator

LhsOwner

RhsOwner

The lhsdata, lhsowner, rhsdata and rhsowner are scopes as described here. Possible values for operator:

* These only work if the operation is performed on a list!

## 3 - Report Metric

Used to record data. Not sure where this data goes…

## 4 - grab

Places the Stack Object in the Sim's (should be the thread's "Me" reference) slot 0.

## 5 - drop

Attempts to place the caller's held object (in slot 0) on an adjacent tile, starting in front.

## 7 - Refresh

Marks an object to be redrawn, update the light map of its room or update the room's room score.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

TargetObj

Unused

RefreshType

Unused

TargetObj:

* 0 - My
* 1 - Stack Object's.

RefreshType:

* 0 - Graphic
* 1 - Lighting Contribution
* 2 - Room Score Contribution

## 8 - Random Number

Sets a variable referenced by a Scope to a random number between 0 and a specified value also referenced by a scope.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

DestData

DestOwner

RangeData

RangeScope

## 9 - burn

Spawns a fire object on the specified location if a fire object is not already there and the object on the space is not busy (or the allow busy objects flag is enabled).

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Location

Flags

Unused

The location can either be 0: Stack Object, 1: in front of stack object or 2: floors under stack object (unused in TSO)

There is only one flag: 1: allow busy objects. If this is not enabled the fire will not spread onto objects that are not idle.

## 10 - Sims1.0 tutorial

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 11 - Get Distance To

Gets the Pythagorean distance between the stack object and the specified object in tiles, floored.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Temp #

Unknown (Flags?)

ObjectScope

OScopeData

Unknown

## 12 - Get Direction To

Gets the direction from the specified object to the stack object and stores it in the specified Scope.

The direction's basis or 0 value "North" is facing from where the house should be AWAY FROM the road. The following values 1-7 are a clockwise rotation around this direction in 45 degree steps, and each has a compass name as you would expect going clockwise corresponding with its direction. The directions of both of the objects are not considered for the calculation, just their positions.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

ResultData

ResultOwner

Unknown (Flags?)

ObjectScope

OScopeData

## 13 - Push Interaction

Pushes an Interaction onto the Stack Object's tree queue.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Interaction #

ObjectLocation

Priority

Flags

IconLocation

Unknown

ObjectLocation's meaning differs based on flags, see below. IconLocation is only regarded when a certain flag is set.

##### Priorities

This would be better on the Interactions page, but it will remain here until we understand more about how they work.

##### Flags

There is functionality for "Interaction result type" and "Server Only (DEV ONLY!)" but I haven't been able to place these on the operand.

## 14 - Find Best Object for Function

Finds an object by function with the relevant Object Data or advertisement set highest, and with its entry point for that function not set to None. This is used for finding sinks, counters, ovens etc (in conjuncton with Get Distance To). If the object's "lockout count" is greater than 0, the object is ignored. This is used to iterate over all of the objects with the function, usually to find the one with the smallest distance. If the primitive finds an object, the stack object is set to it and the primitive returns true, however if the primitive cannot find any objects, it returns false.

This is heavily used by the "Food Chain" group of interactions and NPC service sims.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Function

Unused

## 15 - Break Point

Pauses execution for further examination if the variable specified by a Scope is not 0.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Data Field

Owner

Unused

## 16 - Find Location For

Finds a location to place the stack object. Can be along object vectors, out of the world and "smoke cloud", a specific mode used for the attack interaction.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Mode

Local #

Flags

Unused

##### Modes

The possible modes are:

 1
 2
 3
 4

##### Flags

 1
 2

## 17 - idle for input

Behaves like the sleep primitive, but can return early if the object has been "notified" out of idle, in which case it also sets Object Data flag 1«6 "notified by idle for input". One example of this is when an interaction is canceled, or when another object uses the primitive "Notify the Stack Object out of Idle". This is commonly used (with a sleep time of 0) to detect if an interaction has been canceled.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Local #

Allow Push?

Unused

Local # specifies the Local Variable the number of ticks are taken from. If "Allow Push" is set to 1, this state is "interruptable" and functions can be pushed onto the stack.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

TargetObj

Flags

Unused

TargetObj: 0 = Me, 1 = Stack Object, 2 = Target (unused)

## 19 - make new character

Makes a new character with the specified Age, Skin Color and Gender. Not used by any objects activated in TSO.

##### Operand (not confirmed)

Offset:

0

1

2

3

4

5

6

7

Meaning:

AgeLocal

SexLocal

GenderLocal

Unused

## 20 - Run Functional Tree

Run one of several types of functions on the stack object. Used to make sims sit down to eat, wash their hands etc as part of an automatic process.

See **Primitive 14 - Find Best Object for Function** above for a the table of functions that can be referenced.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Function

Flags

Unused

The only flag seems to be bit 1: change icon. This changes the behavior icon to that of the stack object (imagine using toilet, when going to wash hands icon changes for sink.

## 21 - show string

Presumably used for debug. Some objects show interesting and original strings such as "can't get to the duck", but it doesn't look like these should normally be used. Nothing shows up in The Sims Complete Collection when this primitive is run.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

String Table #

(String ID - 1)

Unused

## 23 - Play Sound Event

Plays the specified sound event.

Offset:

0

1

2

3

4

5

6

7

Meaning:

Event ID

Unknown

Flags

Volume (0-100)

Unused

Flags:

## 24 - old relationship

Gets the relationship between two objects. Used by the pool table to determine the player number of people and sometimes used by social interactions to keep track of who people are talking to etc. This is an old system for doing this, but objects still use it.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Get/Set

Relationship Var

Parameter #

Affected Parties

Flags

Unknown

Get/Set determines whether or not the relationship value will be retrieved from or set to the parameter specified by Parameter #. 0 = Get, 1 = Set.

Relationship Var determines the relationship variable to access. Not sure what these are right now - looks like each object has its own specific strings!

Flags: 1 = fail if too small, 2 = use neighbors

## 25 - Transfer Funds

A more fleshed out version of Alter Budget from The Sims 1, allowing more options such as transfer of funds between people, to maxis, from maxis and to generic objects such as the tip jar! Not sure how this works or what the operand is right now.

## 26 - Relationship

Tracks "relationship" variables of one object to another. Relationships are kept between avatar-lot transfers (not sure about object relationships), so care will have to be taken when storing relationships to avatars (use avatar id instead of object id).

Offset:

0

1

2

3

4

5

6

7

Meaning:

Relationship Var

Mode

Flags

Local #

Variable Scope

Variable Data

The primitive usually gets/sets the relationship variable into/to the specified variable.

##### Modes

There are 4 modes for the Relationship primitive:

0: from me to stack object

1: from stack object to me

2: from stack object to object in local (Specified by Local #)

3: from object in local to stack object (Specified by Local #)

##### Flags

 2
 3

## 28 - Run Tree by Name

This primitive runs the tree referenced by the name in the specified string on either the stack object or itself.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

String Table ID for Tree Names

String Scope (1: global, 0: private)

Unused

String# - 1

Destination

Unused

##### Destination Values:

0: run in my stack (non-yielding)

1: run in stack object's stack (non-yielding)

2: push onto my stack (yielding)

## 29 - Set Motive Change

Sets a motive to change at a specific rate until it hits the specified value. You can clear all changes by setting the Clear All? flag.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

PerHrOwner

StopValueOwner

Target Motive

Clear All?

PerHrData

StopValueData

The values for the change per hour and value to stop at are accessed via Scopes. If Clear All? is set, all motive changes on this sim are cleared. The Target Motive uses the same ID format as Motive Data.

## 30 - Syslog

Used to log information from objects. Seems to always log a string from private String Table 308.

## 31 - Set to Next

Sets the specified variable referenced by a Scope to the object ID of the first object it can find (after the last one) using the search parameters. Used to iterate over objects of a specific type, people etc. Returns false after all objects of that type have been iterated over.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

GUID (if applicable)

Mode

LhsOwner

Value

LhsData

##### Modes

If the highest bit (128) of the Modes field is set the left hand side field is used. If not then the object ID is stored in the stack object.

## 32 - Test Object Type

Tests an object's type against a specified GUID.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

GUID

TargetData

TargetOwner

## 33 - find 5 worst motives

Places 5 worst motives into temps 0-4. Each temp references a Motive Data entry, and they are ordered by lowest first. Only used twice in TSO… npcportal.iff and pedportal.iff (for determining why a sim decided to leave).

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Unused

Target

Motive Type

Target: 0 = me, 1 = stack object, 2 = target object (?)

Motive Type: 0 = Motive, 1 = Mental Motive, 2 = Physical Motive

## 35 - Special Effect

Shows a Picture in Picture display on the specified object (always the stack object). Can also center the camera on an object and slow time down to 1 speed (like the fire).

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Timeout (seconds)

Window Size

Zoom Level

Flags

(Caption STR# - 1)

Unused

Window Size: 0 = small, 1 = medium, 2 = large

Zoom Level: 1 = near, 2 = mid, 3 = far

The caption is always read from string table 305.

## 36 - Dialog - Private Strings

Very complicated, not much info on this one and the text exported versions seem to be missing a lot of info. I probably won't be able to get the operand for this one until much later.

##### Dialog Types:

 1
 2
 3
 4
 5

Text Entry also has a "filter profanity" flag which causes the text entry to return false on detecting any profanity. Temp can either be 0 or 1.

##### Behavior

Engage (OLD) - ???

Continue (OLD) - ???

Engage - ???

Continue - ???

Not sure what the difference between these is. Both are used in their fair share of dialogs.

##### Icon

 1
 2
 3
 4

Strings can be set for the Message, Yes Button, No Button, Title, Cancel Button and Icon Name. Each presumably takes up a byte in the operand to reference the relevant string id, leaving 2 bytes for the other data… This will most likely be complicated. Strings are always chosen from string table ID 301 (called "Dialog prim string set").

Do not take any information in this section as final!

## 37 - Test Sim Interacting With

Returns true if this sim is interacting with the Stack Object, false otherwise. Used to allow interactions like "wake up" for sims already sleeping in the tent and disallow it otherwise.

## 38 - Dialog - Global Strings

Same as 36 except instead accessed global strings. TSO only.

## 39 - Dialog - Semi-Global Strings

Same as 36 except instead accessed semi-global strings. TSO only.

## 40 - OnlineJobsCall

Calls one of the built in functions relating to OnlineJobs. Any that require input, like "Is Job Available" use the value in temp 0.

##### Operand (NOT VERIFIED)

Offset:

0

1

2

3

4

5

6

7

Meaning:

Call#

Unused

## 41 - Set Balloon/Headline

Sets the balloon over a Sim's head to display with the specified icon or clear.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Target

Icon #

Icon Group

Duration (Ticks/Loops)

Balloon Type

Flags

Target: 0 = Me, 1 = Stack Object

If Ticks is 0, the Balloon/Headline is cleared. If Ticks is -1 (all bits set), the duration will be forever

## 42 - Create New Object Instance

Creates a new Object Instance with the GUID specified in the location specified. The new object ID is placed in the stack object. If the object cannot be created, the primitive returns false.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

GUID

Position

Flags

Local To Use (if specified)

Interaction Callback

##### Interaction Callback

Upon running the init function of the created object, if the Return immediately flag is set the Interaction specified by Interaction Callback is queued onto the Stack Object (at the time and same thread this primitive was run) with its Parameter 0 set to the object ID. This is used extensively by the social interaction objects to create AND INIT the objects before running the function from them. This functionality replaces the default where the new object is placed into the stack object, but the primitive still returns true or false depending on whether the creation succeeded or not.

A value of 254 means "Call This Tree".

## 43 - drop onto

Drops an object from the specified slot of the Me object onto the specified slot on the Stack Object.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

SrcSlotMode

SrcSlotNum

DestSlotMode

DestSlotNum

The mode determines where to get the slot number - 0 for literal and 1 for retrieval from a parameter.

## 44 - Animate Sim

Plays an animation on the thread this primitive is run on's Sim. After playing the animation the primitive acts as an event listener, calling the false branch when an animation event (xevt) is called and the true branch when the animation is finished, and waits in place until one of these happens. When looped back to from the false branch and still playing the animation the primitive will resume event listening. If there have been multiple events since the last time the primitive was listening, it favors the most recent one, or if the animation has already ended, the true branch.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Animation ID

LocalEventNumber

Source

Flags

ExpectedEvents

ExpectedEvents should be set to the number of events in the animation, but can be set to 0. If it is 0, it has no effect.

If Animation ID is 0, the current animation is stopped.

##### Animation Source

 1
 2
 3

##### Flags

The "unknown" flags are:

- Interruptable

- Hurryable

- Full Reset

- Behaviour: A 2 bit collection of animation modes, which are:

 1
 2
 3

Since the only 2 bit space is 3&4, this probably fits in there.

## 46 - Snap

Instantly moves the sim to a position retrieved from a routing slot without walking the sim there. Used for objects which move the sim using custom animations (or to positions inside them and back out), like stairs.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Index

Mode

Flags

Unused

##### Modes

The Snap to Routing Slot primitive has multiple modes which allow the primitive to do a variety of things:

0 - Slot Number in parameter:

Snaps to a routing slot (type 3) owned by this object, with index specified by the parameter specified by the "Index" part of the operand.

1 - Be contained in stack object:

Snaps the sim into containment slot 0 (type 0, index 0) of the stack object. If the object is dragged while in this state, the sim will be attached to the object like a plate is on a table.

2 - Be in front of the stack object:

Snaps the sim to be directly in front of the stack object. Direction is supposedly unchanged.

3 - Slot Number:

Snaps to a routing slot (type 3) owned by this object, with index specified by the "Index" part of the operand.

4 - Slot Number:

Snaps to a global routing slot (type 3), with index specified by the "Index" part of the operand.

##### Flags

1: Origin only

2: Ask person to move (asks sims idling on the snap location to move)

3: Use footprint extensions (???)

## 47 - reach

Plays the appropriate reach animation on the sim depending on object height and if the sim is sitting, and can attempt to grab/drop an item on its animation event.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Mode

Attempt to grab/drop?

Slot Param

Unused

Mode can be:

0: Reach to stack object, 1: Reach to slot on stack object, 2: Reach to mouth (unused)

When mode 1 is specified, the slot to reach to is retrieved from the parameter specified by "Slot Param".

## 48 - Stop ALL Sounds

Stops ALL sounds (yes, ALL!) of the specified object.

##### Operand:

Offset:

0

1

2

3

4

5

6

7

Meaning:

Target

Unused

Target: 0 = me, 1 = stack object.

## 49 - Notify the Stack Object out of Idle

Signals the Stack Object out of an idle primitive. Works for both idle for input and Sleep. Counters and Fence Objects usually use this to notify other fence objects to change their appearance, but some other objects use it to facilitate group interaction around a single animated parent object (eg. the pool table).

## 50 - Add/Change the Action String

Changes the current interaction's name to the specified string.

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

String Table ID

Unknown

(String# - 1)

Unused

## 51 - prim 51 - (used in Sims 2.0)

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 52 - prim 52 - (used in Sims 2.0)

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 53 - prim 53 - (used in Sims 2.0)

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 54 - prim 54 - (used in Sims 2.0)

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 55 - Sync Field

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 56 - Ownership

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 57 - Start Persistant Dialog

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 58 - End Persistant Dialog

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 59 - Update Persistant Dialog

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 60 - Poll Persistant Dialog

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 62 - Invoke Plugin

Used to hook an object into a plugin UI, aka an EOD. This is used for interactions such as the pizza table.

## 63 - Get Terrain Info

Gets information on the terrain at the position of a specified object. Can either be Me or the Stack Object. (decided by flags)

##### Operand

Offset:

0

1

2

3

4

5

6

7

Meaning:

Mode

Flags

Unused

##### Modes

 1
 2
 3
 4

##### Flags

 2
 3-8

## 64 - Leave Lot and Goto

*This primitive isn't used in any of the behaviors found in The Sims Online.*

## 65 - Find Best Action

Same as TS1 Find Best Interaction, though Free Will was never included in TSO so this primitive was initially replaced with Report Metric. This finds the "best" interaction the sim can perform, eg. the one with the highest advertisments for their lowest motives and other factors. Used for cat and dog free will. Presumably just pushes it to their queue once it finds one, since I can't find anything that queues it afterwards… Returns false when no interaction is found (the sim is suitably satisfied with their current motives, or there is no object to cater to them).