Script bindings: Utilities¶

Verified against: SLUS_212.15 (NTSC-U, SHA1 e9cb2cc49aa046b9e494313dce2f5038ed17b2f4).

Bindings for numbers, platform queries and generic object queries: 8 in all. Conventions, the other categories and how to read an entry are on the masterlist.

Binding	Returns	Scripts	Boot	Mission 1	Evidence
`GetName`	string	0	no	no	confirmed (code)
`GetPlatform`	number	3	yes	no	confirmed (code)
`GetPosition`	usertype	71	yes	no	confirmed (code)
`GetRTTI`	number	2	no	no	confirmed (code)
`isRelease`	boolean	36	yes	no	confirmed (code)
`random`	number	111	yes	yes	confirmed (code)
`TestDistance`	boolean	16	yes	no	confirmed (code)
`ToInt`	number	6	yes	yes	confirmed (code)

GetName¶

GetName(object) -> string

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Any object handle.

Returns string (nil for none): The object's name (vtable +0x14), or a fixed string (0x0057de50) for a bad handle.

Returns an object's name. No shipped script calls it.

Evidence: confirmed (code) at 0x003859a0; detail: brief
Wrapper 0x0036c978 (registered by RegisterBindings); calls 0x003859a0
Used by no script on the disc
Coney: not implemented

GetPlatform¶

GetPlatform() -> number

No arguments.

Returns number: Always 1 on the PS2 (0x00357998); the scripts test 2 for another platform.

Returns the platform number; config_preload2.lua stores it as Platform to choose PS2 wording such as button names.

Evidence: confirmed (code) at 0x00357998; detail: traced
Wrapper 0x0036d5e0 (registered by RegisterBindings); calls 0x00357998
Used by 3 of 467 script chunks (4 references); boot to menu: yes; mission 1: no; result used: yes
Later in the story: 1 of 28 levels, first level93 (mission 10)
Coney: implemented

GetPosition¶

GetPosition(object) -> usertype

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of a human or any other object.

Returns tolua object (nil for none): An M_Vector4 (x, y, z, w) with the position in world units; the origin vector when the handle is bad.

Returns an object's position. For a human it is the character's position, for other objects their vtable position.

Notes. The vector is one static buffer (0x006ebd20): every call overwrites it, so copy x, y, z before calling again.

Evidence: confirmed (code) at 0x00385a50; detail: traced
Wrapper 0x0036ca18 (registered by RegisterBindings); calls 0x00385a50
Used by 71 of 467 script chunks (193 references); boot to menu: yes; mission 1: no; result used: yes
Later in the story: 23 of 28 levels, first level80 (mission 2)
Coney: implemented

GetRTTI¶

GetRTTI(object) -> number

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Any object handle.

Returns number: The object's type bits with bit 0x2 cleared, as an unsigned number; 0 for a bad handle: a human 0x60, a car 0x100000, a world object (prop, weapon, pick-up, door) 0x08, a particle system or tag 0x10, a flag 0x80, a glass pane 0x400, a scene 0x800, a light task 0x04, a volume box 0x100, a camera 0x200.

Returns an object's run-time type bits, the word its vtable slot +0x24 gives, which the game's own casts test (a human 0x40 at 0x00229868, a flag 0x80 at 0x00417a60, a prop 0x08 at 0x00395f38, a tag 0x10 in ProcessTag). A script tests one bit to learn what kind of object a handle names.

Notes. Each task class returns a constant (Tasks: type bits); bit 0x2 is set for every task, so masking it leaves only the class bits. The human's 0x20 is not traced.

Evidence: confirmed (code) at 0x00385950; detail: traced
Wrapper 0x0036c888 (registered by RegisterBindings); calls 0x00385950 Object_GetTypeBits
Used by 2 of 467 script chunks (3 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 2 of 28 levels, first level34 (mission 4)
Coney: implemented

isRelease¶

isRelease() -> boolean

No arguments.

Returns boolean (1 for true, nil for false): Always true (1).

Tells the scripts this is a release build (0x00357990), which turns off their debug helpers.

Evidence: confirmed (code) at 0x00357990; detail: traced
Wrapper 0x0036d5a8 (registered by RegisterBindings); calls 0x00357990
Used by 36 of 467 script chunks (72 references); boot to menu: yes; mission 1: no; result used: yes
Later in the story: 15 of 28 levels, first level87 (mission 3)
Coney: implemented

random¶

random(low, high) -> number

#	Argument	Read as	Meaning
1	`low`	number, truncated to an integer	Lowest value.
2	`high`	number, truncated to an integer	Highest value.

Returns number: A whole number in [low, high], both included: low + (the next entry of a 1,024-entry table at 0x005117e0) mod (high - low + 1), unsigned.

Returns a random whole number in a range; replaces the math library's random.

Notes. The generator's state is only the table index at 0x006eb880 (advanced by 1, masked to 10 bits, per draw), zeroed at start-up and never seeded; C++ code draws from the same index. A test mode should seed Coney's own generator.

Evidence: confirmed (code) at 0x00386488; detail: traced
Wrapper 0x0036dfc8 (registered by RegisterBindings); calls 0x00386488
Used by 111 of 467 script chunks (343 references); boot to menu: yes; mission 1: yes; result used: yes
Later in the story: 23 of 28 levels, first level80 (mission 2)
Coney: implemented

TestDistance¶

TestDistance(a, b, distance) -> boolean

#	Argument	Read as	Meaning
1	`a`	number, truncated to an unsigned integer	First object handle.
2	`b`	number, truncated to an unsigned integer	Second object handle.
3	`distance`	number (single precision)	Distance in world units (metres).

Returns boolean (1 for true, nil for false): true if the objects are closer than distance; false otherwise or when a handle is bad.

Tests whether two objects are closer than a distance: both handles are resolved (a bad one gives false), their positions read, and the squared distance compared with the squared limit, so exactly at the limit counts as not closer.

Evidence: confirmed (code) at 0x00385ea8; detail: traced
Wrapper 0x0036ce58 (registered by RegisterBindings); calls 0x00385ea8
Used by 16 of 467 script chunks (38 references); boot to menu: yes; mission 1: no; result used: yes
Later in the story: 21 of 28 levels, first level80 (mission 2)
Coney: implemented

ToInt¶

ToInt(x) -> number

#	Argument	Read as	Meaning
1	`x`	number (single precision)	A number.

Returns number: x truncated toward zero, after a round trip through a 32-bit float (so values above 2^24 lose precision).

Converts a number to an integer by truncation.

Evidence: confirmed (code) at 0x0036d938; detail: traced
Wrapper 0x0036d938 (registered by RegisterBindings); calls nothing (the wrapper does the work itself)
Used by 6 of 467 script chunks (7 references); boot to menu: yes; mission 1: yes; result used: yes
Later in the story: 28 of 28 levels, first level80 (mission 2)
Coney: implemented