Script bindings: Effects and lighting¶

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

Bindings for particles, weather, fog, lights, shadows, gamma and screen effects: 43 in all. Conventions, the other categories and how to read an entry are on the masterlist.

Binding	Returns	Scripts	Boot	Mission 1	Evidence
`AddOneOffEmitter`	number	0	no	no	inferred
`AddStatRespEmitter`	number	0	no	no	speculative
`EnableGroundFog`	-	0	no	no	confirmed (code)
`EnableHeat`	-	1	no	no	confirmed (code)
`EnableShadow`	-	4	no	yes	confirmed (code)
`End3DFog`	-	40	yes	no	confirmed (code)
`EndFilmGrain`	-	0	no	no	confirmed (code)
`EndFog`	-	34	yes	no	confirmed (code)
`EndGarbage`	-	7	yes	no	confirmed (code)
`EndParticle`	-	16	no	no	confirmed (code)
`EndRain`	-	43	yes	no	confirmed (code)
`EndRoomSmoke`	-	39	yes	no	confirmed (code)
`GetGamma`	number	0	no	no	confirmed (code)
`InitFallingEmbers`	-	1	no	no	confirmed (code)
`KillParticle`	-	11	no	no	confirmed (code)
`MaxFogParticles`	-	7	no	no	inferred
`ParticleChangeState`	-	1	no	no	confirmed (code)
`QueueMotionBlurEffect`	-	4	yes	yes	confirmed (code)
`ScreenQueueEffect`	-	169	yes	yes	confirmed (code)
`SetFogColor`	-	66	no	yes	confirmed (code)
`SetFogDistance`	-	14	no	no	confirmed (code)
`SetGamma`	-	1	no	no	confirmed (code)
`SetGammaOffset`	-	1	yes	no	confirmed (code)
`SetGammaRamp`	-	0	no	no	confirmed (code)
`SetLevelColour`	-	2	yes	no	confirmed (code)
`SetLight`	number	61	yes	yes	confirmed (code)
`SetLightFlicker`	-	9	no	no	confirmed (code)
`SetMotionAlpha`	-	3	yes	no	confirmed (code)
`SetShadowColor`	-	1	yes	no	confirmed (code)
`SetShadowLightOffset`	-	1	yes	no	confirmed (code)
`SetWorldAmbient`	-	3	yes	no	confirmed (code)
`SpawnAreaEffect`	-	1	no	no	confirmed (code)
`SpawnParticle`	number	36	no	yes	confirmed (code)
`SpawnRainPlane`	-	3	no	no	confirmed (code)
`Start3DFog`	-	17	no	no	confirmed (code)
`StartFilmGrain`	-	0	no	no	confirmed (code)
`StartFog`	-	0	no	no	confirmed (code)
`StartGarbage`	-	2	yes	no	confirmed (code)
`StartParticle`	-	20	no	no	confirmed (code)
`StartRain`	-	10	no	no	confirmed (code)
`StartRoomSmoke`	-	8	no	no	confirmed (code)
`TermFallingEmbers`	-	1	no	no	confirmed (code)
`WidgetSetColour`	-	2	no	no	confirmed (code)

AddOneOffEmitter¶

AddOneOffEmitter(pos, sound, volume) -> number

#	Argument	Read as	Meaning
1	`pos`	table of 3 numbers (t[1]..t[3])	World position `{x, y, z}`.
2	`sound`	number, truncated to an integer	Sound id.
3	`volume`	number (single precision)	Number passed to the audio manager (volume or radius).

Returns number: Number returned by the audio manager (an emitter handle).

Plays a one-off positional sound through the audio manager (0x00110e58). No script calls it.

Evidence: inferred; detail: brief
Wrapper 0x003724d8 (registered by RegisterBindings); calls 0x00113b78 AmbientSound_AddOneOff
Used by no script on the disc
Coney: not implemented

AddStatRespEmitter¶

AddStatRespEmitter(name, pos, params, p1, p2, p3) -> number

#	Argument	Read as	Meaning
1	`name`	string	Emitter name.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position `{x, y, z}`.
3	`params`	table of 5 numbers (t[1]..t[5])	Five numbers passed to the audio manager.
4	`p1`	number, truncated to an unsigned integer	Number passed to the audio manager.
5	`p2`	number, truncated to an unsigned integer	Number passed to the audio manager.
6	`p3`	number, truncated to an integer	Integer passed to the audio manager.

Returns number: Number returned by the audio manager (an emitter handle).

Adds a sound emitter that responds to a game statistic, through the audio manager (0x00110e28 on 0x0050aa84). No script calls it.

Notes. Belongs with the sound bindings; left in this category because of its name. The 'statistic response' reading is a guess from the name.

Evidence: speculative; detail: brief
Wrapper 0x00371938 (registered by RegisterBindings); calls 0x00113a08 AmbientSound_AddStatResponse
Used by no script on the disc
Coney: not implemented

EnableGroundFog¶

EnableGroundFog(enable)

#	Argument	Read as	Meaning
1	`enable`	boolean (nil or 0 is false)	True to start, false to stop the ground fog camera effect.

Returns nothing.

Switches the ground-fog camera effect (ICameraGroundFog, 0x005971a4) on or off. No script calls it.

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

EnableHeat¶

EnableHeat(enable)

#	Argument	Read as	Meaning
1	`enable`	boolean (nil or 0 is false)	True switches both views to look 7 (heat); false ends it and returns to the base look.

Returns nothing.

Switches the heat look (screen-effects look 7, Screen effects) on or off on both screen-effects managers. On, each view makes look 7 current and blends its tint and motion-blur strength to look 7's over look 7's in time (default 1 s); off, it goes back to the base look (the level colour, look 9, or the store look) over look 7's out time (default 5 s).

Notes. What the player sees is whatever look 7 holds: its defaults (no tint, blur 1) can be changed by CfgScrFx before. No distortion pass of its own was found; the "heat" is the tint and blur blend (inferred from 0x0018b7d0).

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

EnableShadow¶

EnableShadow(object, enable)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Ignored.
2	`enable`	boolean (nil or 0 is false)	Ignored.

Returns nothing.

Does nothing in this build: its callee (0x0017f270) is empty. Scripts call it to hide characters' shadows, with no effect.

Evidence: confirmed (code) at 0x0017f270; detail: traced
Wrapper 0x0037c748 (registered by RegisterBindings); calls 0x0017f270 Shadow_Enable_Stub
Used by 4 of 467 script chunks (23 references); boot to menu: no; mission 1: yes; result used: no
Later in the story: 2 of 28 levels, first level52 (mission 15)
Coney: implemented

End3DFog¶

End3DFog()

No arguments.

Returns nothing.

Destroys the 3D fog objects of both screen-effects managers (message 0x15) and clears their handles; global.lua calls it when resetting effects.

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

EndFilmGrain¶

EndFilmGrain()

No arguments.

Returns nothing.

Stops the film grain screen effect (effect 2) on the first screen-effects manager only. No script calls it.

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

EndFog¶

EndFog()

No arguments.

Returns nothing.

Stops the screen fog effect (effect 1) on both screen-effects managers; global.lua calls it when resetting effects.

Evidence: confirmed (code) at 0x0018dfa8; detail: traced
Wrapper 0x00368ea0 (registered by RegisterBindings); calls 0x0018dfa8 ScreenFx_EndFog
Used by 34 of 467 script chunks (34 references); boot to menu: yes; mission 1: no; result used: no
Coney: not implemented

EndGarbage¶

EndGarbage()

No arguments.

Returns nothing.

Stops the blowing-litter camera effect.

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

EndParticle¶

EndParticle(particle)

#	Argument	Read as	Meaning
1	`particle`	number, truncated to an unsigned integer	Handle of the particle system or script-typed object.

Returns nothing.

Sends message 0x13 ("off") to the object's task: a particle system stops emitting (the fire types clear their on flag and stop, 0x003c9f78), and a plain object (simple_object) is hidden. The object itself is not destroyed, so StartParticle can start it again.

Notes. Each type's message handler decides; types that do not handle 0x13 ignore it. Whether particles already in flight finish their life is up to each type (not traced in general).

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

EndRain¶

EndRain()

No arguments.

Returns nothing.

Stops the rain screen effect (effect 0) on both screen-effects managers. global.lua calls it when it resets a level's weather.

Evidence: confirmed (code) at 0x0018deb0; detail: traced
Wrapper 0x00368970 (registered by RegisterBindings); calls 0x0018deb0 ScreenFx_EndRain
Used by 43 of 467 script chunks (45 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 5 of 28 levels, first level93 (mission 10)
Coney: not implemented

EndRoomSmoke¶

EndRoomSmoke()

No arguments.

Returns nothing.

Stops the room smoke screen effect (effect 3) on both screen-effects managers.

Evidence: confirmed (code) at 0x0018e0f8; detail: traced
Wrapper 0x00368fb8 (registered by RegisterBindings); calls 0x0018e0f8 ScreenFx_EndRoomSmoke
Used by 39 of 467 script chunks (39 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level5 (mission 7)
Coney: implemented

GetGamma¶

GetGamma() -> number

No arguments.

Returns number: Current brightness 0-255 (the light manager's value × 255).

Returns the display brightness. No script calls it.

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

InitFallingEmbers¶

InitFallingEmbers(object, minRate, maxRate)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of the object (a flag) the embers fall around; its position is taken once. A bad handle does nothing.
2	`minRate`	number, truncated to an unsigned integer	Fewest embers per second (divided by 30, whole numbers, for a per-frame count); the script passes 80.
3	`maxRate`	number, truncated to an unsigned integer	Most embers per second, likewise divided by 30; the script passes 110.

Returns nothing.

Starts (creating it on first use, 0x005971ac) the falling-embers effect of a burning building and centres it on the object. Each frame it spawns a random count between minRate/30 and maxRate/30 embers at random points of a 10 x 10 m horizontal square around the centre; each is a sprite (sheet 1, rectangles 8-10) with a random brightness 128-225 that falls under 0.8-1.0 of gravity and lives 2-3 s (60-90 frames).

Notes. Counts and times are per frame (fixed 30 Hz). A second call only moves the centre and changes the rates. The meaning of ember +0x28 as brightness is inferred; the draw is not traced.

Evidence: confirmed (code) at 0x00179758, 0x00178fd8, 0x00179310, 0x00179378; detail: traced
Wrapper 0x003781d8 (registered by RegisterBindings); calls 0x00179758 Embers_Init, 0x00178fd8, 0x00179310, 0x00179378 Embers_Update
Used by 1 of 467 script chunks (2 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level93 (mission 10)
Coney: not implemented

KillParticle¶

KillParticle(particle)

#	Argument	Read as	Meaning
1	`particle`	number, truncated to an unsigned integer	Handle of the particle system (as returned by the particle-creating bindings); a stale or nil handle does nothing.

Returns nothing.

Sends message 0x15 (destroy) to the object at once through the task manager, bracketed by the manager's enter/leave pair (0x003a2d20, 0x003a2d40): the particle system stops and is removed by its own message handler (Particles, Tasks: messages).

Notes. The handle is not checked to be a particle: any object that handles message 0x15 (glass, glints, objects) is destroyed the same way; whether a system fades out or vanishes depends on its type's handler, not traced per type.

Evidence: confirmed (code) at 0x00397730, 0x003a2e00; detail: traced
Wrapper 0x00379288 (registered by RegisterBindings); calls 0x00397730 Particle_Kill, 0x003a2e00 Task_SendMessage
Used by 11 of 467 script chunks (297 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 8 of 28 levels, first level95 (the hub)
Coney: implemented

MaxFogParticles¶

MaxFogParticles(count)

#	Argument	Read as	Meaning
1	`count`	number, truncated to an unsigned integer	Maximum number of live fog wisps per view (10 or 15 in the scripts; Start3DFog's emitter keeps 20 otherwise).

Returns nothing.

Sends message 0x22 with the count to the 3D fog emitter of each of the two screen-effects managers (handle at +0x218), lowering how many wisps Start3DFog keeps alive. Call it after Start3DFog; with no fog running it does nothing.

Notes. The send is confirmed (code) at 0x0018e2f0; the part_fog emitter's handling of message 0x22 (replacing the 20-wisp top-up) is not traced.

Evidence: inferred; detail: traced
Wrapper 0x003692b0 (registered by RegisterBindings); calls 0x0018e2f0 Fog3D_SetMaxParticles
Used by 7 of 467 script chunks (7 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level34 (mission 4)
Coney: implemented

ParticleChangeState¶

ParticleChangeState(particle, state)

#	Argument	Read as	Meaning
1	`particle`	number, truncated to an unsigned integer	Handle of the particle system or other scripted world object (a handle that does not resolve sends to nothing).
2	`state`	number, truncated to an integer	The value put in the message; its meaning is the receiving type's (the one script call passes a hit count).

Returns nothing.

Sends task message 25 (0x19) with state as its argument to the object, delivered at once to its type's message handler (Tasks: messages). Particle and script types switch on 0x19 among their messages (Particles); for doors and breakables the same message sets hitpoints (World objects); WidgetSetColour's message form uses it too.

Notes. What each particle type does with message 0x19 is not traced; inferred from the script's use: it sets how many hits or which stage an effect object shows.

Evidence: confirmed (code) at 0x00397660, 0x003a2e00; detail: traced
Wrapper 0x00379198 (registered by RegisterBindings); calls 0x00397660 Particle_ChangeState, 0x003a2e00 Task_SendMessage
Used by 1 of 467 script chunks (1 reference); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level86 (mission 9)
Coney: not implemented

QueueMotionBlurEffect¶

QueueMotionBlurEffect(colour, seconds)

#	Argument	Read as	Meaning
1	`colour`	table of 4 numbers (t[1]..t[4])	Blur colour `{r, g, b, a}` (0-255) to blend to. Written back unchanged.
2	`seconds`	number (single precision)	Blend time in seconds.

Returns nothing.

Blends the motion-blur effect of the first screen-effects manager to a new strength (or colour) over a time, for hit and slow-motion moments.

Notes. Both forms end in 0x0018c8c8 on the manager at 0x005fdeb8 (0x0040cd28 for the colour form, 0x0040cce8 for the alpha form).

Overload (registered first; the wrapper above checks its argument types and calls this one when they do not match): Used when the first argument is not a table (the form every script uses, such as QueueMotionBlurEffect(150, 1) in the first mission's tutorial).

QueueMotionBlurEffect(alpha, seconds)

#	Argument	Read as	Meaning
1	`alpha`	number, truncated to an unsigned integer	Target motion-blur strength 0-255.
2	`seconds`	number (single precision)	Blend time in seconds.

Returns nothing.

Wrapper 0x0037be18; calls 0x0040cce8.

Evidence: confirmed (code) at 0x0040cd28; detail: traced
Wrapper 0x0037be90 (registered by RegisterBindings); calls 0x0040cd28 ScreenFx_QueueMotionBlurColour
Used by 4 of 467 script chunks (14 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 1 of 28 levels, first level95 (the hub)
Coney: implemented

ScreenQueueEffect¶

ScreenQueueEffect(effect, seconds)

#	Argument	Read as	Meaning
1	`effect`	number, truncated to an integer	Effect type 0-5 (Screen effects): 0 fades in from black, 1 fades out to black, 2 and 3 bring the letterbox in and out, 4 and 5 start and end the blur pulse. Values 6 and above do nothing.
2	`seconds`	number (single precision)	Duration in seconds (0 makes the change immediate).

Returns nothing.

Queues a full-screen effect, usually a fade, on both screen-effects managers. A running fade blocks some menu input and is what the front end waits on (Front end).

Notes. Dispatch is a six-entry jump table at 0x00552f70 (0x0018d450); each type is described on Graphics. A fade out of more than 0.2 s runs over seconds - 0.2; a fade in starts at full black; the level is clamped to 0-1 (Front end).

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

SetFogColor¶

SetFogColor(r, g, b)

#	Argument	Read as	Meaning
1	`r`	number (single precision)	Red, 0-1.
2	`g`	number (single precision)	Green, 0-1.
3	`b`	number (single precision)	Blue, 0-1.

Returns nothing.

Sets the colour of the world's distance fog (packed to bytes with alpha 255 and handed to the fog object at 0x0050cdb4). level99.lua's Main calls it first.

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

SetFogDistance¶

SetFogDistance(distance)

#	Argument	Read as	Meaning
1	`distance`	number (single precision)	Fraction of the draw distance at which fog begins: 0 starts the fog at the camera (thick haze), 1 at the draw distance (almost none); the scripts pass 0 or 0.5, and 0.5 is the default.

Returns nothing.

Sets where the world fog starts: the graphics device's fog start (device +0x444, through its slot +0x54), a fraction of the draw distance. Each frame the world renderer sets the fog distance to draw distance × this value (halved for one object list), and the fog fades to the colour set with SetFogColor.

Notes. Not range-checked. Not reset by the level code that was read, so the value stays until a script sets it again (inferred). Draw distance and fog: The streamed world.

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

SetGamma¶

SetGamma(level)

#	Argument	Read as	Meaning
1	`level`	number, truncated to an unsigned integer	Brightness 0-255 (larger values are clamped to 255; the profile screen uses 0-100, 40 by default); stored in the game state (+0x57a4) and added as level/255 to every ambient and directional light.

Returns nothing.

Sets the brightness: the byte W_GameState + 0x57a4 (saved with the profile) and the light manager's brightness offset +0x90 = level / 255 on every ambient and directional light. PM_Light and the options menu call the same function with 0-100 (40 by default). See Saving.

Evidence: confirmed (code) at 0x001b4838; detail: traced
Wrapper 0x0037bc98 (registered by RegisterBindings); calls 0x001b4838 Gamma_Set
Used by 1 of 467 script chunks (5 references); boot to menu: no; mission 1: no; result used: no
Coney: not implemented

SetGammaOffset¶

SetGammaOffset(offset)

#	Argument	Read as	Meaning
1	`offset`	table of 3 numbers (t[1]..t[3])	Colour offset `{r, g, b}` (small values; `global.lua` passes the level's `LightData.goffset`). Written back unchanged.

Returns nothing.

Sets the light manager's colour offset (+0xa0, through 0x0017ec80), added with the brightness to every ambient and directional light's colour.

Notes. docs/research/lighting.md#colour.

Evidence: confirmed (code) at 0x001b4908; detail: traced
Wrapper 0x0037bd30 (registered by RegisterBindings); calls 0x001b4908 LightManager_SetColourOffset
Used by 1 of 467 script chunks (1 reference); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

SetGammaRamp¶

SetGammaRamp(red, green, blue)

#	Argument	Read as	Meaning
1	`red`	table of 256 numbers (t[1]..t[256])	Read (256 numbers) but ignored.
2	`green`	table of 256 numbers (t[1]..t[256])	Read (256 numbers) but ignored.
3	`blue`	table of 256 numbers (t[1]..t[256])	Read (256 numbers) but ignored.

Returns nothing.

Does nothing in this build: its callee (0x0018e7d0) is empty.

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

SetLevelColour¶

SetLevelColour(colour)

#	Argument	Read as	Meaning
1	`colour`	table of 4 numbers (t[1]..t[4])	Overlay colour `{r, g, b, a}`, components 0-1 (scaled to 0-255); `a` sets how strongly it tints the screen. Written back unchanged.

Returns nothing.

Sets a full-screen colour overlay (screen effect 9) that tints the whole level, used for each level's lighting mood.

Evidence: confirmed (code) at 0x0018e5f0; detail: traced
Wrapper 0x003683d0 (registered by RegisterBindings); calls 0x0018e5f0 ScreenFx_SetColourOverlay
Used by 2 of 467 script chunks (2 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level55 (mission 17)
Coney: implemented

SetLight¶

SetLight(light, state) -> number

#	Argument	Read as	Meaning
1	`light`	number, truncated to an unsigned integer	Handle of a light made by the long form.
2	`state`	number, truncated to an unsigned integer	0 switches the light off, 1 (any non-zero but 2) on, 2 removes it.

Returns number: The light's handle, or 0 when it was removed or the handle was 0.

Creates, changes, switches or removes a dynamic light in the light manager. global.lua builds each level's moonlight, reflected light and ambient light with it.

Notes. Long form 0x0017ef20, short form 0x0017f160, both on the light manager at 0x0050cce4. The type mapping to RenderWare (0 → 0x80 point, 1 → 0x81 spot, 2 → 1 directional, 3 → 2 ambient) is confirmed (code), and so are the corona, lights and effects arguments (0x0017c508, 0x0017caa8, 0x0017d880; confirmed (runtime) in level99). See docs/research/lighting.md#record.

Overload (registered first; the wrapper above checks its argument types and calls this one when they do not match): The long form, which every script uses (always 14 arguments); the short form is selected only when exactly two numbers are passed.

SetLight(light, type, pos, dir, colour, radius, coneAngle, coronaHeight, coronaPull, coronaSize, lights, effects, corona, state) -> number

#	Argument	Read as	Meaning
1	`light`	number, truncated to an unsigned integer	0 to create a new light, or the handle of an existing light to change.
2	`type`	number, truncated to an unsigned integer	Light type: 0 point, 1 spot, 2 directional, 3 ambient (RenderWare light types; values above 3 are refused).
3	`pos`	table of 3 numbers (t[1]..t[3])	Position `{x, y, z}` in world metres (point and spot lights). Written back unchanged.
4	`dir`	table of 3 numbers (t[1]..t[3])	Direction `{x, y, z}` (spot and directional lights). Written back unchanged.
5	`colour`	table of 4 numbers (t[1]..t[4])	Colour `{r, g, b, a}`, components 0-1 (such as `{1, 0.75, 0, 1}`). Written back unchanged.
6	`radius`	number (single precision)	Radius in metres for point and spot lights (must not be negative).
7	`coneAngle`	number (single precision)	Cone angle for spot lights (must not be negative); the scripts pass 1 for other types.
8	`coronaHeight`	number (single precision)	Metres the corona sits above the light (record +0x0c); level99 uses 0 to -1.15.
9	`coronaPull`	number (single precision)	Metres the corona is moved towards the camera (+0x10); must not be negative when a corona is set.
10	`coronaSize`	number (single precision)	The corona's size in metres (+0x14), also the cull radius of a light with radius 0; same rule.
11	`lights`	number, truncated to an unsigned integer	What the light lights, 0-3 (refused above 3): bit 0 objects and humans, bit 1 the world.
12	`effects`	number, truncated to an unsigned integer	0-32 (refused above 32): bit 0 spawns part_light_bugs at the light; bits 1-4 a flicker mode (2 random brightness, 4 random fade).
13	`corona`	number, truncated to an unsigned integer	Corona sprite 0-6: 0 none, 1-6 rectangle 0-5 of the lighting sheet.
14	`state`	number, truncated to an unsigned integer	1 creates or leaves the light on, 0 off, 2 removes an existing light.

Returns number: The light's handle (new or existing), or 0 when the arguments were refused or the light was removed.

Wrapper 0x0037bfb8; calls 0x0017ef20.

Evidence: confirmed (code) at 0x0017f160; detail: traced
Wrapper 0x0037c348 (registered by RegisterBindings); calls 0x0017f160 Light_SetState
Used by 61 of 467 script chunks (5301 references); boot to menu: yes; mission 1: yes; result used: yes
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

SetLightFlicker¶

SetLightFlicker(light, onTime, onRandom, offTime, offRandom, pause, pauseRandom, burst, burstRandom, flickerTime, dim)

#	Argument	Read as	Meaning
1	`light`	number, truncated to an unsigned integer	Handle of a light made by `SetLight`.
2	`onTime`	number, truncated to an unsigned integer	Blink mode: ms the light stays on (the scripts pass 100).
3	`onRandom`	number, truncated to an unsigned integer	Blink mode: up to this many ms more, at random.
4	`offTime`	number, truncated to an unsigned integer	Blink mode: ms the light stays dimmed; 0 selects burst mode instead.
5	`offRandom`	number, truncated to an unsigned integer	Blink mode: up to this many ms more, at random.
6	`pause`	number, truncated to an unsigned integer	Burst mode: ms of steady light between bursts.
7	`pauseRandom`	number, truncated to an unsigned integer	Burst mode: up to this many ms more; in blink mode, a first delay when not 0.
8	`burst`	number, truncated to an unsigned integer	Burst mode: flickers in a burst.
9	`burstRandom`	number, truncated to an unsigned integer	Burst mode: up to this many flickers more.
10	`flickerTime`	number, truncated to an unsigned integer	Burst mode: each flicker lasts up to this many ms (random).
11	`dim`	number, truncated to an unsigned integer	Brightness in percent: blink mode's dimmed level; burst mode's upper bound of a random level.

Returns nothing.

Makes a light blink (offTime not 0) or flicker in bursts (offTime 0) through 0x0017d0b0; a light with radius 0 becomes a sub_flashing_light particle instead. Does nothing for light 0.

Notes. The modes and timings are on docs/research/lighting.md#flicker.

Evidence: confirmed (code) at 0x0017f1b8; detail: traced
Wrapper 0x0037c438 (registered by RegisterBindings); calls 0x0017f1b8 Light_SetFlicker
Used by 9 of 467 script chunks (163 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 6 of 28 levels, first level95 (the hub)
Coney: implemented

SetMotionAlpha¶

SetMotionAlpha(alpha)

#	Argument	Read as	Meaning
1	`alpha`	number, truncated to an unsigned integer	Motion-blur strength 0-255 (0 off, 255 strongest); the scripts use 15 normally.

Returns nothing.

Sets the motion-blur (frame trail) strength on both screen-effects managers at once (+0x1a4 and +0x1a8), unless a game-state check (0x0041d110) blocks it.

Notes. The wrapper calls 0x0040cc70 directly.

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

SetShadowColor¶

SetShadowColor(r, g, b)

#	Argument	Read as	Meaning
1	`r`	number (single precision)	Ignored.
2	`g`	number (single precision)	Ignored.
3	`b`	number (single precision)	Ignored.

Returns nothing.

Does nothing in this build: its callee (0x0017f260) is empty, although global.lua calls it.

Evidence: confirmed (code) at 0x0017f260; detail: traced
Wrapper 0x0037c608 (registered by RegisterBindings); calls 0x0017f260 Shadow_SetColour_Stub
Used by 1 of 467 script chunks (1 reference); boot to menu: yes; mission 1: no; result used: no
Coney: not implemented

SetShadowLightOffset¶

SetShadowLightOffset(x, y, z)

#	Argument	Read as	Meaning
1	`x`	number (single precision)	Ignored.
2	`y`	number (single precision)	Ignored.
3	`z`	number (single precision)	Ignored.

Returns nothing.

Does nothing in this build: its callee (0x0017f268) is empty, although global.lua calls it.

Evidence: confirmed (code) at 0x0017f268; detail: traced
Wrapper 0x0037c6a8 (registered by RegisterBindings); calls 0x0017f268 Shadow_SetLightOffset_Stub
Used by 1 of 467 script chunks (1 reference); boot to menu: yes; mission 1: no; result used: no
Coney: not implemented

SetWorldAmbient¶

SetWorldAmbient(r, g, b)

#	Argument	Read as	Meaning
1	`r`	number (single precision)	Red, 0-1.
2	`g`	number (single precision)	Green, 0-1.
3	`b`	number (single precision)	Blue, 0-1.

Returns nothing.

Sets the world's ambient light colour; the game adds 0.07 to each component, so (0, 0, 0) still leaves a little light.

Notes. Stored in the light manager (0x0050cce4) at +0x50..+0x5c.

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

SpawnAreaEffect¶

SpawnAreaEffect(human, radius, damage, excludeSelf, sparedKind)

#	Argument	Read as	Meaning
1	`human`	number, truncated to an unsigned integer	Handle of the human at the centre, who is also the attacker; a handle that is not a human does nothing.
2	`radius`	number (single precision)	Radius in metres (20 in the one script call).
3	`damage`	number, truncated to an unsigned integer	Damage dealt to each human hit (100 in the script call).
4	`excludeSelf`	boolean (nil or 0 is false)	true spares the centre human himself (true in the script call).
5	`sparedKind`	number, truncated to an integer	Gang kind (gang `+0x2c`) whose members are spared, or -1 for none (6 in the script call).

Returns nothing.

Deals a one-off blast of damage around a human, as an explosion does (Explosion_DamageHumansInRadius): up to 60 humans within the radius of his centre are found, and each one with a clear line from the centre (a world ray cast) gets the damage as pending damage from him, with a hit reaction, through the normal damage path (Combat: damage). Used once, in a boss fight.

Notes. Humans the centre human counts as friends (0x00222a90) get the damage negated and no reaction, so (inferred) they take none. Nothing is drawn or played by this call; any visual comes from the script.

Evidence: confirmed (code) at 0x00385b08, 0x00392638; detail: traced
Wrapper 0x0036ca88 (registered by RegisterBindings); calls 0x00385b08 AreaEffect_Spawn, 0x00392638 Explosion_DamageHumansInRadius
Used by 1 of 467 script chunks (1 reference); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level55 (mission 17)
Coney: not implemented

SpawnParticle¶

SpawnParticle(typeName, pos, rot, attachTo) -> number

#	Argument	Read as	Meaning
1	`typeName`	string	Particle object type name, such as `part_spray_tag`.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position `{x, y, z}`. Written back unchanged.
3	`rot`	table of 4 numbers (t[1]..t[4])	Orientation quaternion `{x, y, z, w}`. Written back unchanged.
4	`attachTo`	number, truncated to an unsigned integer	Handle of an object to attach the particle system to, or NilHandle for none.

Returns number: Handle of the particle object.

Creates a particle-system object of a configured type at a position, optionally attached to another object, and returns its handle.

Evidence: confirmed (code) at 0x0039bfb0; detail: traced
Wrapper 0x00378958 (registered by RegisterBindings); calls 0x0039bfb0 Particle_Spawn
Used by 36 of 467 script chunks (596 references); boot to menu: no; mission 1: yes; result used: yes
Later in the story: 24 of 28 levels, first level80 (mission 2)
Coney: implemented

SpawnRainPlane¶

SpawnRainPlane(corner, cornerU, cornerV, uv0, uv1)

#	Argument	Read as	Meaning
1	`corner`	table of 3 numbers (t[1]..t[3])	First corner `{x, y, z}` of the rain sheet in world metres.
2	`cornerU`	table of 3 numbers (t[1]..t[3])	The corner along the sheet's width.
3	`cornerV`	table of 3 numbers (t[1]..t[3])	The corner along the sheet's height; the three corners also give the side it is seen from.
4	`uv0`	table of 2 numbers (t[1]..t[2])	Read and written back but not used: the sheet takes its texture coordinates from the rain layer (scripts pass `{0, 0}`).
5	`uv1`	table of 2 numbers (t[1]..t[2])	Read and written back but not used (scripts pass `{1, 1}`).

Returns nothing.

Adds a world-space sheet of falling rain (for doorways, windows and awnings) to a list of at most 25 kept at 0x005fdec0; further calls do nothing. While StartRain is running and the overlay is switched to world sheets (rain object +0x90), each sheet whose front faces the camera (normal (cornerU - corner) × (cornerV - corner)) is drawn with both rain layers' textures, scrolling with them.

Notes. The record is 0x28 bytes and only its three corners are written; the draw also reads +0x24 (compared with 12 to halve the repeats), left unset here. What sets rain object +0x90 (inferred: the camera under cover) is not traced. The rain copies the list when it is created (0x00199ba8), so sheets added while it runs are drawn only after EndRain and a new StartRain.

Evidence: confirmed (code) at 0x0018dd38, 0x0018be58, 0x0019a780, 0x0019a8e0; detail: traced
Wrapper 0x00368990 (registered by RegisterBindings); calls 0x0018dd38 ScreenFx_SpawnRainPlane, 0x0018be58, 0x0019a780, 0x0019a8e0
Used by 3 of 467 script chunks (27 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level93 (mission 10)
Coney: not implemented

Start3DFog¶

Start3DFog(texture, colour, drift, fadeSpeed, fadeRate)

#	Argument	Read as	Meaning
1	`texture`	number, truncated to an unsigned integer	Sprite word of the fog wisp image: sheet-table record in the top 16 bits, rectangle in the low 16. 15 of the 17 calls pass 34734080 (0x2120000): record 530, the sheet `part_fog_00`; the other two 34799616 (0x2130000): record 531, `part_fog_01`; each one 64 × 64 texture, rectangle 0.
2	`colour`	table of 4 numbers (t[1]..t[4])	Wisp colour `{r, g, b, a}`, 0-255; alpha is the opacity a wisp fades in to. Written back unchanged.
3	`drift`	number (single precision)	Speed each wisp drifts at, metres per second (× 1.75-2.25 at random), toward the player's camera with a sideways spread of up to ±2 m along the camera's x axis; scripts use 0.4-4.6.
4	`fadeSpeed`	number (single precision)	Sets the fade-in length: 9 / fadeSpeed steps (at least 1); scripts use 0.3-1.
5	`fadeRate`	number (single precision)	Whole-number multiplier on the opacity added per fade step; scripts use 1-7.

Returns nothing.

Starts drifting ground fog for each player's view: for both screen-effects managers it kills any fog emitter (message 0x15) and creates a part_fog emitter (template 0x00552fb8). Every 5 frames the emitter tops its viewport up to 20 live wisps (sub_fog, up to 10 at a time), placed at random within 20 m of the camera's target and 0.5-2 m above it, each drifting toward the camera and fading in to the colour's alpha. Details: Particles, Drifting fog.

Notes. Wisps are dropped when their viewer is more than 20 m away or a near test fails, and hidden within 4 m. MaxFogParticles changes the 20. The three numbers' visible effect is read from sub_fog's init (0x003ca658) and update (0x003ca9d8); units are not runtime-checked. Arguments renamed from size, speed, height.

Evidence: confirmed (code) at 0x0018e148, 0x003cadd8; detail: traced
Wrapper 0x00369140 (registered by RegisterBindings); calls 0x0018e148 Fog3D_Start, 0x003cadd8
Used by 17 of 467 script chunks (17 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 6 of 28 levels, first level87 (mission 3)
Coney: implemented

StartFilmGrain¶

StartFilmGrain(texture, colour, p1, p2)

#	Argument	Read as	Meaning
1	`texture`	number, truncated to an unsigned integer	Read but ignored.
2	`colour`	table of 4 numbers (t[1]..t[4])	Read but ignored.
3	`p1`	number, truncated to an unsigned integer	Read but ignored.
4	`p2`	number, truncated to an unsigned integer	Read but ignored.

Returns nothing.

Does nothing in this build: its callee (0x0018dff8) is empty.

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

StartFog¶

StartFog(texture, colour, p1, p2, p3, p4, p5, p6, p7, p8, p9)

#	Argument	Read as	Meaning
1	`texture`	number, truncated to an unsigned integer	Sprite word of the fog texture (Particles: sprite words).
2	`colour`	table of 5 numbers (t[1]..t[5])	Five numbers 0-255: the tint `{r, g, b}` (the record's alpha is 0), then the lowest and highest alpha a drift may pick.
3	`p1`	number (single precision)	Lowest sideways scroll per update, in texture widths.
4	`p2`	number (single precision)	Highest sideways scroll per update.
5	`p3`	number (single precision)	Lowest vertical scroll per update (given a random sign).
6	`p4`	number (single precision)	Highest vertical scroll per update.
7	`p5`	number (single precision)	Largest width scale before the 1/0.7 factor (a drift picks 1.43 to `p5` / 0.7).
8	`p6`	number (single precision)	Largest height scale (a drift picks 1.0 to `p6`).
9	`p7`	number (single precision)	A third range, plus or minus `p7`: blended with the others but not used by the draw.
10	`p8`	number, truncated to an unsigned integer	Shortest blend from one drift to the next, in milliseconds.
11	`p9`	number, truncated to an unsigned integer	Longest blend, in milliseconds.

Returns nothing.

Starts the screen-space fog overlay (screen-effects layer 1, OE_Fog) on both views: one full-screen sprite of the texture, tinted, that scrolls and drifts between random settings the way the room smoke does. No script calls it; levels use Start3DFog and the world fog colour instead.

Notes. How a drift is picked and blended, and how the camera's turning scrolls it: Graphics.

Evidence: confirmed (code) at 0x0018df00, 0x00199380, 0x001996b0, 0x00199a50; detail: traced
Wrapper 0x00368c40 (registered by RegisterBindings); calls 0x0018df00 ScreenFx_StartFog, 0x00199380 OE_Fog_Construct, 0x001996b0 OE_Fog_PickDrift, 0x00199a50 OE_Fog_Update
Used by no script on the disc
Coney: not implemented

StartGarbage¶

StartGarbage(kind)

#	Argument	Read as	Meaning
1	`kind`	number, truncated to an unsigned integer	Litter kind 0-3 (`part_page1` rectangles 54-58, 30-32, 8-11 or 18; sizes about 0.4, 0.4, 0.06-0.13 or 0.17-0.2 m; 0 is the one `global.lua` uses); other values do nothing.

Returns nothing.

Starts the blowing-litter camera effect (ICameraGarbage, 0x005971a0): 64 flat cards of litter on an 8 × 8 grid (7 m apart) around the camera, each falling, tumbling and blown by the wind vector at 30 Hz, settling on the ground and respawning when it leaves a 28 m square around the camera or its 600-900-update life ends. Not drawn while a scene plays. Details: Particles, Blowing litter.

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

StartParticle¶

StartParticle(particle)

#	Argument	Read as	Meaning
1	`particle`	number, truncated to an unsigned integer	Handle of a particle system or another script-typed object (from `SpawnParticle`, `ObjSpawn` or a level's object table).

Returns nothing.

Sends message 0x12 ("on") to the object's task with an empty message scratch. What it does depends on the object's script type: a particle system starts emitting (the fire types set their on flag and start their flame, 0x003c8b28), and a plain object (simple_object) is shown again.

Notes. Each type's message handler decides; types that do not handle 0x12 ignore it. Messages: World objects, types: Particles.

Evidence: confirmed (code) at 0x003975c0; detail: traced
Wrapper 0x00379128 (registered by RegisterBindings); calls 0x003975c0 Particle_Start
Used by 20 of 467 script chunks (48 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 13 of 28 levels, first level80 (mission 2)
Coney: implemented

StartRain¶

StartRain(texture1, tilesV1, tilesU1, driftU1, fallV1, colour1, texture2, tilesV2, tilesU2, driftU2, fallV2, colour2)

#	Argument	Read as	Meaning
1	`texture1`	number, truncated to an unsigned integer	Sprite word of the near rain layer's texture: sheet in the top 16 bits, rectangle in the low (Particles: sprite words).
2	`tilesV1`	number, truncated to an unsigned integer	How many times the texture repeats down the screen (byte; scripts use 1 or 2).
3	`tilesU1`	number, truncated to an unsigned integer	How many times it repeats across the screen (byte; scripts use 6 or 7).
4	`driftU1`	number (single precision)	Sideways scroll per frame in texture widths (0.01-0.015 in the scripts: a slant).
5	`fallV1`	number (single precision)	Downward scroll per frame in texture heights (0.07-0.3: the fall speed).
6	`colour1`	table of 4 numbers (t[1]..t[4])	Layer 1 colour `{r, g, b, a}`, 0-255 (the alpha sets how heavy it looks).
7	`texture2`	number, truncated to an unsigned integer	Sprite word of the second (far) layer's texture.
8	`tilesV2`	number, truncated to an unsigned integer	Vertical repeats of layer 2.
9	`tilesU2`	number, truncated to an unsigned integer	Horizontal repeats of layer 2.
10	`driftU2`	number (single precision)	Sideways scroll per frame of layer 2.
11	`fallV2`	number (single precision)	Downward scroll per frame of layer 2.
12	`colour2`	table of 4 numbers (t[1]..t[4])	Layer 2 colour `{r, g, b, a}`, 0-255.

Returns nothing.

Starts the rain effect (screen-effects layer 0, OE_Rain) on both views, or changes its settings when it is already running. Each layer is a textured sheet drawn over the view (and on every rain plane from SpawnRainPlane) whose texture coordinates span tilesU × tilesV repeats and scroll each frame by (driftU, fallV), wrapping at 1, so the streaks fall and slant. It also switches on the ground splashes that CfgRaindrops configures.

Notes. Scrolling is per rendered frame, not per second. The sheet's size follows a fixed field-of-view scale (1.7, 2.0 in one display mode, times 1.15 in one game state, 0x0019a8e0). EndRain stops it. The colour tables are written back as read.

Evidence: confirmed (code) at 0x0018dda0, 0x0018bae0, 0x00199ba8, 0x00199e50, 0x0019a8e0; detail: traced
Wrapper 0x00368670 (registered by RegisterBindings); calls 0x0018dda0 ScreenFx_StartRain, 0x0018bae0, 0x00199ba8, 0x00199e50, 0x0019a8e0
Used by 10 of 467 script chunks (22 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 5 of 28 levels, first level93 (mission 10)
Coney: not implemented

StartRoomSmoke¶

StartRoomSmoke(colour, amount)

#	Argument	Read as	Meaning
1	`colour`	table of 5 numbers (t[1]..t[5])	Five numbers 0-255: the haze tint `{r, g, b}`, then the lowest and highest alpha a drift may pick (the scripts pass `{120, 120, 140, 220, 240}`); written back unchanged.
2	`amount`	number (single precision)	Scales how fast the haze drifts sideways (a random 0.0005-0.0015 screen widths per update times this, either way); scripts use about 0.5.

Returns nothing.

Starts the room-smoke overlay (screen effect layer 3, OE_RoomSmoke) on both views: a full-screen smoke texture tinted with the colour that slowly scrolls and changes. Every 4-20 s (random) it picks a new drift: a sideways speed scaled by amount, a scale of 1.63-1.93 by 1.0-1.2, and an alpha between the fourth and fifth colour values. Calling it while the layer runs passes the new settings to the running effect. EndRoomSmoke stops it.

Notes. The record's own alpha byte is always 0; the visible alpha comes only from the drift range. The texture (room_smoke_overlay), the blend from one drift to the next (0x0019b2a8) and the camera follow (0x0019b070): Graphics.

Evidence: confirmed (code) at 0x0018e070, 0x0018bae0, 0x0019add0, 0x0019b198, 0x0019b4c0; detail: traced
Wrapper 0x00368ec0 (registered by RegisterBindings); calls 0x0018e070 ScreenFx_StartRoomSmoke, 0x0018bae0, 0x0019add0 OE_RoomSmoke_Construct, 0x0019b198 OE_RoomSmoke_PickDrift, 0x0019b4c0 OE_RoomSmoke_Update
Used by 8 of 467 script chunks (8 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 5 of 28 levels, first level5 (mission 7)
Coney: implemented

TermFallingEmbers¶

TermFallingEmbers()

No arguments.

Returns nothing.

Stops the falling embers: deletes the embers object (0x005971ac) with every ember still falling, so they vanish at once. Does nothing when no embers are running.

Evidence: confirmed (code) at 0x001797e8, 0x001790a8; detail: traced
Wrapper 0x00378278 (registered by RegisterBindings); calls 0x001797e8 Embers_Term, 0x001790a8
Used by 1 of 467 script chunks (2 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level93 (mission 10)
Coney: not implemented

WidgetSetColour¶

WidgetSetColour(object, colour, viaMessage)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of a world object (scripts pass coloured-light props of the funfair level).
2	`colour`	table of 4 numbers (t[1]..t[4])	Table {r, g, b, a}, each 0-255 (the low byte of each is used), packed as 0xRRGGBBAA; written back unchanged.
3	`viaMessage`	boolean (nil or 0 is false)	true sends the colour to the object as task message 25 (0x19) through the task manager; false writes it straight into the object.

Returns nothing.

Recolours a world object. Without viaMessage the packed colour is stored in both colour words of the object (+0xb0 and +0xb4, 0x001e9ac0; an unresolved handle does nothing); with it the colour is put in a task message and delivered at once to the object's message handler (vtable +0xcc), which applies it in its own way.

Notes. Which object classes read +0xb0/+0xb4 and how the handler of the prop class used treats message 25 are not traced; for breakable objects message 25 sets hitpoints (World objects), so the message form only suits classes that read it as a colour. The name says widget, but the handle is a world object.

Evidence: confirmed (code) at 0x0039c2e0, 0x001e9ac0, 0x003a2e00; detail: traced
Wrapper 0x00378b00 (registered by RegisterBindings); calls 0x0039c2e0 Obj_SetWidgetColour, 0x001e9ac0, 0x003a2e00 Task_SendMessage
Used by 2 of 467 script chunks (4 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level81 (mission 8)
Coney: not implemented