Redguard Preservation

Reference documentation for The Elder Scrolls Adventures: Redguard (1998) file formats, engine behavior, and undocumented features. The documentation covers the GOG release’s Glide renderer and notes known original-CD differences.

Reference sections

• Engine behavior: scripting, actor animation, movement, rendering, audio, menus, and hidden cheats.
• File formats: binary layouts for models, maps, textures, sound, saved state, and bundled support files.
• Configuration: INI settings for worlds, combat, items, input, rendering, and menus.

Look and feel

Reproducing the look and feel explains how terrain and model lighting, fog, sky, water, texture animation, camera projection, and on-screen presentation combine, with links to each subsystem.

Starting points

Engine lineage

Redguard runs on Bethesda’s XnGine, a DOS-based 3D engine. Battlespire used its own build of the engine, and Redguard added 3dfx Glide support.

Terminator and Daggerfall files share structure with Redguard’s:

Terminator scenes use a cell grid with linked entity lists, not RGM sections.

Related community work:

• XnGine: game list and engine history.
• skynet-godot wld_terrain.gd: Terminator WLD layout and height table.
• skynet-godot mesh_3d.gd: Terminator .3D header offsets and texture ids.
• skynet-godot texture_nnn.gd: Terminator TEXTURE.NNN layout.
• skynet-godot map_file.gd: Terminator MAP layout.
• UESP: Daggerfall Mod:WOODS.WLD format and Daggerfall Unity WoodsFile.cs: Daggerfall terrain file layout.
• Daggerfall Unity Arch3dFile.cs: Daggerfall .3D header and texture ids.
• Daggerfall Unity and terminator-unity: a Daggerfall reimplementation, and an effort to extend it to the Terminator games.

Installation contents

Main Files

Asset Directories

Asset and support-file roles

Models, textures, fonts, UI images, maps, dialogue, sound effects, movie data, and CD music supply the content of a faithful reimplementation. Hardware configuration, audio-utility launch settings, SideWinder presets, and tool reports describe the original environment. Their layouts remain part of the format references in Bundled support resources.

The cursor file system/pointers.bmp contains a GXA archive despite its extension. fxart/fxart.txt and fxart/fxart3dc.txt are historical directory listings, and fxart/LOGFILE.TXT records collision-sphere generation. The support-file reference describes these files and the Miles setup catalog sound/MSSDRVR.LST.

Save-game containers describe SAVEGAME.SAV and the per-world .TSG snapshots. A slot’s LOGBOOK.TXT is journal content.

GOG vs original CD differences

The English CD installer contains software and Glide resources. GOG selects the Glide distribution and omits the software-specific asset directory and executable. The game data, renderer choice, configuration defaults, and host packaging are separate parts of edition compatibility.

Executables and installation layout

RGFX.EXE is byte-identical between the English CD payload and GOG. The Windows REDGUARD.EXE launchers differ; they are not the DOS rendering executables. The CD places the DOS executables outside DATA1.CAB, so extracting that cabinet alone does not produce a runnable installation.

Renderer-specific assets

GOG’s fxart/ contents are byte-identical to the English CD installer payload. GOG does not include 3dart/.

The directories overlap in model names, but are not interchangeable copies. Glide includes additional standalone models; software includes additional ROB archives. Even matching names can have different geometry and animation data: TIRBA001.3DC has different face and frame counts, and NCROCK.3D has different face counts. Resolve resources within the chosen renderer’s asset set rather than substituting a same-named file from the other set.

Both model generations use renderer-specific headers and texture references. See 3D model versions. Software texture banks are named TEXTURE.###, not TEXBSI.###; changing the filename prefix does not establish format compatibility. See software texture banks and software palette lookup tables.

3dart/ contains 18 COL palettes, including art_pal.col, world palettes, and sky palettes. It does not use art_pal.col exclusively. Matching palette names can differ between renderers: NECRO2.COL and REDGUARD.COL have different contents. The Glide set contains 27 populated COL palettes and an empty CLDTEST.COL placeholder. See COL palettes.

Shared content

The English CD installer payload and GOG share byte-identical:

• RGM scenes and their embedded scripts, WLD terrain, and PVO visibility data;
• SOUP386.DEF, WORLD.INI, COMBAT.INI, ITEM.INI, MENU.INI, KEYS.INI, REGISTRY.INI, and surface.ini;
• ENGLISH.RTX dialogue and speech, MAIN.SFX, and the other sound resources except the configured dig.ini and mdi.ini device selections;
• fonts and system artwork, including title, menu, HUD, and sky images.

Renderer-specific model and texture differences therefore coexist with shared authored scenes, scripts, and presentation resources.

Configuration defaults

GOG changes these values relative to the English CD installer’s SYSTEM.INI:

These are stored settings, not differences in the shared game scripts. animation_drive differs only in drive-letter capitalization, d:\ versus D:\. The software [screen] resolution remains 1 in both configurations. See SYSTEM.INI for field meanings and renderer overrides.

The CD cabinet’s sound/dig.ini and sound/mdi.ini contain setup comments without device selections. GOG supplies Sound Blaster device and driver settings. Hardware configuration belongs to the installation environment; it does not replace the game’s Red Book music tracks.

Cinematics, disc audio, and support files

The CD Smacker movies are byte-identical to those in GOG’s data track, including their embedded audio. GOG’s virtual disc omits the CD’s installer cabinet, DOS engines, setup files, and bundled hardware-driver installers. Its ISO9660 filenames FINDRE~1.EXE and REDGUA~1.ICO refer to the same contents as the CD’s FindRedguard.exe and RedguardCD.ICO.

An extracted CD data directory contains movies and installation files, but not the Red Book audio tracks. Mounting that directory as a CD-ROM cannot reconstruct the missing music tracks. A music-capable disc source must retain the audio tracks and their numbering; separately distributed soundtrack files are not a substitute for the disc’s track layout. See background music.

GOG adds host Glide libraries and DOSBox launch configuration. The selected Glide implementation determines the splash variant independently of the shared Glide executable. See startup presentation.

Engine behavior

Runtime rules for scripts, actors, world rendering, sound, and presentation. The file format references describe the stored data; the configuration reference describes the INI settings.

Scripting and actors

World rendering

Look and feel connects the visible result to the rendering and presentation rules below.

Start with the Glide shading overview for flat and smooth shading, the color pipeline, and links to the detailed rules.

Audio and presentation

SOUP Scripting

Bytecode scripting engine used by the Redguard runtime for actor behavior, dialogue, puzzle logic, and scene control.

Function overview

SOUP386.DEF declares callable functions in installed order. Index 0 is the synthetic NullFunction; authored entries start at index 1. See SOUP386.DEF for function IDs and parameter declarations, and function dispatch for argument evaluation and task lifetime.

Shared actor setup, navigation, family transforms, and model admission are specified alongside the functions that use them below.

Script Data Sources

What Is In the Runtime vs Data Files

• Runtime contains the SOUP VM/interpreter and native handlers for script-callable operations.
• Script payload data is loaded from map/script assets (RGM and .AI) and executed by the VM.
• Function names and metadata come from SOUP386.DEF, while actor-local script bytes come from RASC/.AI content.

VM Architecture

The SOUP386 VM is a register-free, program-counter-driven bytecode interpreter. There is no operand stack — values flow through function return values and are consumed directly by the calling instruction. Local variables (RAVA section, per-actor int[]) and global flags (369 entries shared across all scripts) provide persistent state.

Threading Model

An actor retains a main continuation and an optional entry continuation in the same bytecode buffer:

The main and entry invocations share bytecode and local variables. Entry processing temporarily replaces the active cursor, then restores the main continuation. The actor has one subroutine return continuation, shared by these invocations, rather than a stack of return addresses.

Execution is cooperative. The original runtime consumes non-blocking instructions until a blocking task or an explicit yield returns control. Existing tasks are revisited before the main script body can continue.

End (opcode 0x05) stores its authored target and ends the current invocation. It does not permanently terminate the actor’s main script. An eligible later invocation resumes at the stored target. Endint (opcode 0x13) resets the active cursor to the script base and returns from the current invocation.

World shell-script preparation

After loading map objects, world loading prepares the available DEBUG, COMMON, and map-specific shell scripts in that order. The debug-shell suppression switch skips DEBUG; disabling shell loading prevents shell-record creation. This preparation precedes the separate CYRUS, GREMLIN, and CAMERA initialization.

Each shell record takes its script continuations and string-table reference from its map definition and receives its own copy of the initial local variables. When the initial script cursor is absent or equals the script base, no separate entry cursor is stored. New shell records are prepended to the shell list.

The map-specific shell script is the script named after the world’s map file (START for START.RGM); a name with no installed script creates no record. SYSTEM.INI [debug] final_version set to a nonzero value skips DEBUG.

Shell script execution

Every world-loop iteration, before the ordinary actor update, each shell record runs in list order, so the newest record runs first. A record runs as an actor without a map object: its attributes and control state are zeroed for the run, while its locals, continuation and task slots persist between runs. Execution is in shell context, in which the weapon, item and activation predicates report no ordinary animation state. KillMe marks the record finished and the engine frees it after that run; a script that never calls it runs every iteration for the rest of the world.

OpenShell(name) and item use create a record from the installed script of that name, copying its initial local variables; names compare without case. A world without the script reports an error. A record created during an iteration first runs in the next one.

Ordinary update gates

SYSTEM.INI’s [system] task_system enables the ordinary entry, task, and main script stages when its numeric value is one. The per-actor RAHK native hook is a separate call record, not the entry continuation. With the task system enabled, the hook is dispatched only when no unpaused task slot exists. With the task system disabled, task-slot occupancy does not suppress that hook. Its own suppression flag still applies in both paths. Actor exclusions and script-name filters apply before these stages.

The actor’s runtime script-control byte has independent effects:

The 0x04 path is distinct from the usual entry, existing-task, then main-body order. It retains the entry continuation’s blocking-operand gate, but bypasses both the existing-task pass and its blocking-task gate before the main body. An existing unpaused blocking slot therefore does not by itself suppress the main body on this path. These runtime flags are not RAHD attribute indices. See actor update order.

DisableScript sets mask 0x01; EnableScript clears only that mask. Both return zero and preserve the other bits. They do not terminate the native call’s current interpreter invocation or clear existing tasks. The wrapper checks the main-stage suppression flag after the native hook and combat processing, so a hook can change eligibility for the same update. Once the wrapper enters either main-stage path, it does not recheck those flags between entry work and the main body.

The native hook precedes the ordinary entry/task/main sequence. When the task system is enabled and no unpaused task exists, combat processing follows the hook for actors with combat state outside shell execution. This includes the selected player; the wrapper does not restrict combat processing to map actors or exclude the selected actor. Combat maintenance applies its own player and nonplayer branches. The entry continuation is processed later inside the enabled main stage. Mask 0x01 does not suppress the separate native hook.

PlayerStand query

PlayerStand(receiver) compares the receiver identity with the selected player’s retained supporting-actor reference. It returns one for equality and zero otherwise. The query performs no collision search and does not update either actor or the retained reference.

PlayerArc query

PlayerArc(offset, tolerance) tests the selected player’s horizontal direction relative to the receiver’s heading. Angles use 2048 units per turn. The query uses the receiver’s attached position when attached, otherwise its linked query position when present, otherwise its local position. It reads the selected player’s local position. Vertical separation does not affect the result.

The receiver heading comes from its attached pose when attached and its local pose otherwise. A linked query position alone does not replace that heading. The query forms the horizontal vector from the player to the receiver with wrapping signed 32-bit subtraction, computes its quantized bearing, and negates that bearing modulo 2048. It subtracts offset from the receiver heading modulo 2048, then compares the absolute shortest wrapped angular difference with the signed tolerance. Equality succeeds; negative tolerance fails.

The query returns one for success and zero otherwise. It performs no visibility or distance test and does not update either actor.

Fighting query

isFighting searches the retained ordinary actor traversal for another actor whose combat target is the receiver. A candidate must have a combat record, its retained attacker-selection state must equal exactly one, and IsDead must return false. Combat construction and reinitialization clear that selection state to zero. This state is distinct from the combat action, maintenance phase and weapon-drawn flag.

The search chooses the first candidate with the smallest rounded three-dimensional distance. Its initial distance bound is 65535 in Q8 coordinates, and replacement requires a strictly smaller distance. Candidates at that bound are excluded; equal distances preserve the earlier actor in traversal order. Position lookup uses each actor’s effective query position, including its normal attachment or linked-position handling.

When a candidate is selected, isFighting returns one only when the rounded horizontal distance to that candidate is strictly less than [misc] in_combat_threshold from COMBAT.INI, shifted left eight bits with 32-bit wrapping. Otherwise it returns zero. The horizontal comparison uses the candidate chosen by three-dimensional distance; it does not perform a second nearest-candidate search. Both distance calculations use the shared mixed-precision integer-distance calculation.

Combat maintenance

A newly constructed combat record has no target, an action selector of -1 and a zero cooldown. Combat construction clears the record before assigning its attribute-derived counters and attack metadata. First allocation assigns the current combat-record allocation counter as its retained allocation index, then increments the counter with 32-bit wrapping. Reinitializing an existing record preserves its allocation index across the clear. Opening a world opens a new object-system session, whose combat-record allocation counter starts at zero. Closing that session releases its object pool.

Fresh map loading initializes type-one placement models in MPOB file order. Cell-owned and separately allocated placements share this traversal; spatial cell order does not reorder their model construction. These map models initialize before the two standalone player models. The initially selected player model is constructed before the alternate player model.

Combat construction copies actor attribute 2 into the record’s strength value and attribute 4 into its armor value (the values Strength, Armor, setStrength and setArmor use). It stores five counters as 129 minus attribute 58, 62, 63, 87 and 88 respectively, and four more as copies of attributes 59, 64, 65 and 66. The nonplayer decision stage uses the counters from attributes 58, 62 and 63 as divisors of its tick-based pacing tests. The action, pending-move and defence selectors start at -1, the aggression budget at 50, the attack state at 0, and combat flag mask 0x08 is cleared.

Combat construction copies RAEX v_vertex as a signed model-vertex index and converts signed v_size to runtime Q8 contact radius by shifting left eight bits. An absent actor-extra record supplies zero for both values.

Combat construction derives three spacing ranges from the nine attack slots. Every populated slot contributes to the divisor. Only slots whose first motion has kind 1 contribute range values. The near range is the smallest attack minimum. The far range starts at zero; when a qualifying first motion’s maximum exceeds the retained far range, the attack maximum replaces that range. The comparison uses the motion maximum, while the assignment uses the attack maximum. For each qualifying slot, the constructor adds the attack minimum plus half of the difference between its maximum and minimum to a signed midpoint sum. The subtraction and additions wrap at 32 bits; division truncates toward zero. The third spacing range is that sum divided by the number of populated slots, including slots whose first motion has another kind. If no slot qualifies, the near, far and third ranges are 10000, 30000 and 20000 respectively.

The motion kind this test reads is the first word of the runtime motion record, which is not the COMBAT.INI type. The type value is stored further into the record. The loader writes 1 in the first word of every attack motion: single attacks of type 0 (melee) and type 3 (stab) and the first moves of combos all carry it, so every populated slot of the installed actors qualifies. For example the three slots of the Vermai fighters (attacks 75, 76 and 77, each with minimum 0, maximum 55000, types 3, 3 and 0) give near 0, far 55000 and third 27500, and the five slots of the START pirates (two combos of maximum 45000 and three singles of maximum 35000, all minimum 0) give near 0, far 45000 and third 19500. The first word of a type 4 (finishing) motion has not been read from the original. The installed COMBAT.INI contains attacks of type 0, 2, 3 and 4 only.

Fight spacing runs only when the action selector is -1. With the combat-stance predicate set, it uses the constructor’s spacing ranges directly. Both stance paths turn toward the target after preparing their ranges and period, and continue only when the absolute returned angle is strictly below 128. Below the near range it tries backward, right and left movement admission in that order, taking the first result equal to 1. Above three times the far range it requests forward walking only if animation group 31 exists. Otherwise, above the third range plus half the difference between the far and third ranges, it requires group 92 and queries forward movement for one update. It requests forward movement only if the target distance minus that amount is at least the third range. All these movement requests use duration 1.

The facing wrapper uses both actors’ local X/Z positions. It first runs the facing-arrival test, using the speed selected by the receiver’s current animation group. Arrival copies the target’s local X/Z to the receiver, leaves Y and heading unchanged, registers the receiver for a deferred map update and returns zero. Otherwise, the quantized actor heading of the local target displacement supplies the desired heading for the ordinary turn helper. Positive X selects 1536, negative X selects 512, positive Z selects zero and negative Z selects 1024. The lower-level bearing result has the opposite sign; that result is negated once to obtain the actor heading. Its result is zero on a snap and otherwise the signed difference from before the turn step; spacing applies its strict angle gate to that result.

The disengaged decision branch aligns toward the retained target point rather than reading the target’s current position. If alignment returns zero, it tries a separate three-dimensional point-arrival test. That test shifts each target and local coordinate right by eight before subtraction. Its Y difference is the target Y minus the sum of local Y and the actor’s positive Y bounds extent, all in integer map units. It uses the same current-group movement attribute as facing, but admits only when rounded distance is strictly less than (speed * 384) >> 8; frame scale does not multiply this threshold. Missing animation or attributes supply speed zero. Admission copies all three target coordinates after shifting right and then left by eight, preserving heading, and refreshes spatial/model registration. Rejection leaves position unchanged. This helper snaps on arrival; it does not move along a path. If neither alignment nor point arrival handles the update, the disengaged branch requests MoveForward(1) when the shared target distance is below 500001, and WalkForward(1) otherwise.

When the combat-stance predicate is zero, spacing replaces the near range with 30000 and triples the far range. It consumes two inclusive 0..32767 random draws. The third range becomes three times its original value plus the allocation index times the first draw scaled by 100 and divided by 32767. The spacing period becomes twice its original value plus the allocation index times the second draw scaled by 10 and divided by 32767. Each random scaling division precedes the allocation-index multiplication. Range, period and index arithmetic wrap at 32 bits.

When execution reaches the remaining spacing branch, it first runs the multiple-attacker spacing helper. If that helper requests no sidestep, it adds the receiver’s allocation index to the shared tick counter with signed 32-bit wrapping. Only a signed remainder of exactly one after division by the effective spacing period requests a random movement. The division truncates toward zero; a zero period or a quotient outside the signed 32-bit range causes a division fault.

The movement choice is an inclusive random draw from 0..32767 multiplied by 20 and divided by 32767. Values below 16 choose backward movement, values 16 and 17 choose right movement, and values 18 through 20 choose left movement. Only the chosen direction’s admission is tested. A result equal to one requests that movement with duration one; any other result leaves movement unchanged, without trying another direction. A successful multiple-attacker sidestep skips both the pacing division and this random draw.

A spacing pass that passes the action-selector and turning gates registers the receiver in the deferred map-update list. This registration also occurs when movement admission rejects every direction, the required animation group is absent, or no movement is requested. Repeated registration retains the first occurrence of each actor. The deferred pass processes registrations in that order, clears the consumed entries and resets the list count.

The combat coordination selector starts at zero, separately from the consecutive close-distance counter. Assigning the coordination selector first clears that counter, then stores the requested selector value.

Combat coordination

The coordination selector is also the attacker-selection state used by attacker iteration. Exactly one admits an attacker. The waiting-state lookup scans the ordinary actor list from its head, excludes the supplied target actor, and chooses the first actor with a combat record, a nonnull combat target, lifecycle selector other than eight and coordination state one. It does not require that actor’s target to equal the supplied target.

The active-state lookup starts after the receiver in ordinary list order and wraps at the list end, stopping before the receiver. It chooses the first other combat actor with the same combat target, lifecycle selector other than eight, and either a held weapon or combat flag mask 0x04. The selected player is excluded.

After successful engagement and both cleanup executors reporting inactive, coordination state one selects the active branch. With negative aggression and an active-state candidate, the candidate’s three-dimensional distance to the selected player must be strictly below three times its far spacing range to send addressed message 0xd002. The range multiplication wraps at 32 bits. That send precedes a kind-nine timed taunt request, then assignment of coordination state zero. Spacing, counter-attack and defense selection still follow this originally selected active branch.

Other coordination values select the waiting branch. An absent waiting-state candidate assigns state one. With a candidate and more than ten consecutive close-distance passes, the receiver sends 0xd003, then requests a kind-eight timed taunt. Spacing follows the waiting branch without counter-attack or defense selection on that pass.

Without engagement, state one runs the active-state lookup and sends 0xd002 when a candidate exists, then assigns state zero. Other states remain unchanged. The retained-target movement helper follows in either case.

Counter-attack timing

Counter selection subtracts the target’s current signed animation command cursor from its current attack motion’s first_collide_frame and first_defend_frame, producing two signed wrapping gaps. It does not use the frame-wait progress byte or the displayed model frame. The target’s retained attack-slot selector and current motion selector choose the motion.

The target motion’s one-based defense reference, minus one with signed wrapping, selects one of the receiver’s four defense slots. That record’s first_collide_frame and collide_duration supply the counter’s timing start and duration. These values are distinct from spatial min_range and max_range.

Counter selection first requires a held weapon, distance strictly inside the target’s spacing window, and an absolute wrapped heading difference greater than 768. The target action must be neither minus one nor nine, the receiver action must be minus one, at least one bound defense must be available, and the target’s attacked flag 0x10 must be clear. Timing and counter-reference queries follow these gates.

An accepted counter preserves the low two intent bits while setting bit 0x02, stores the pending counter index, invokes the synchronous attack starter, then sets the target’s attacked flag. The target mark follows the starter’s return. A deterministic timing miss steps right for an even pacing sum or left for an odd sum when the target’s retained attack selector is three or four; otherwise it steps backward. These movements use duration one and call the movement primitive directly, without the spacing helper’s additional obstacle admission.

The attack starter first rejects drawing or sheathing, then requires action minus one. For a nonplayer it retains the pending index, assigns action nine and invokes the attack executor. The selected player’s pending-index selection is separate.

Attack executor

The attack executor resolves its pending move through the four defense slots bound from attributes 79 through 82, rather than the nine attack slots. An idle cleanup request does not inspect move metadata. An idle non-cleanup request compares the current animation group with the pending move’s group. If they differ, it makes a forced animation request with modifier zero, sets the finite loop countdown to one and clears the animation’s pending group. Only then does it set combat attack state to two and subtract ten from the aggression budget with signed 32-bit wrapping. An already-current group leaves the record unchanged.

With nonzero attack state and a pending move, leaving that move’s animation group clears attack state and the pending move. The action selector also clears when it is nine. The executor reports active exactly when attack state is nonzero and a move remains pending.

Multiple-attacker spacing

The multiple-attacker spacing helper traverses the current target’s attacker list in ordinary actor-list order. First and next queries exclude the target itself and require a combat record targeting it, retained attacker-selection state exactly one, and a false IsDead result. Its initial primary neighbor is the first attacker, unless that attacker is the receiver. It starts a retained distance at 65535. For each later attacker other than the receiver, a horizontal query distance strictly below the retained distance replaces the primary neighbor and moves the former primary into the secondary slot. Equal distances retain the existing pair. The initial attacker is not distance-tested, and the secondary slot is the preceding primary rather than a separately selected second-nearest attacker.

The neighbor-distance query uses horizontal Euclidean distance in runtime Q8 units. For each actor, a nonzero attr_slave selects attached position; otherwise a valid linked positioned record supplies position, with ordinary local position as the fallback. It subtracts the receiver’s X/Z from the candidate’s X/Z with signed 32-bit wrapping and supplies zero for the Y difference. Each difference is stored as single precision. The sum of squares passes through a double-precision store before an extended-precision square root; the stored single-precision root converts to an integer with nearest-even rounding. This position selection differs from the local-position vectors used by the separation query below.

For each retained neighbor, the helper forms receiver-minus-target and neighbor-minus-target vectors from local Q8 positions. Each subtraction wraps at signed 32 bits, then each component shifts arithmetically right eight before vector-to-angle conversion. The separation is the receiver vector’s Y angle minus the neighbor vector’s Y angle: both angles are masked to 2047 and the difference wraps into the inclusive range -1024 through 1024. The two exact half-turn signs remain distinct. An absent neighbor supplies 1024 without converting either vector. Vector-to-angle conversion first normalizes all three vector components to length 65536. Each signed component is stored as single precision. Their sum of squares passes through a double-precision store before an extended-precision square root. The root multiplied by 1/65536 is stored as a single-precision divisor. A zero divisor produces a zero vector. Otherwise each component divided by that divisor is stored as single precision, then converted to a signed integer with nearest-even rounding. The angle conversion consumes this normalized vector. Its Y angle is the negative of the quantized actor heading from normalized X/Z, minus 1024, wrapped modulo 2048. Normalized Y influences this result through the shared three-dimensional normalization, even though the heading query itself uses only X/Z. The zero vector produces Y angle 1024. Normalization can round a small horizontal component to zero, so taking the heading directly from the unnormalized displacement is not equivalent.

The threshold is [misc] non_engaged_spacing from COMBAT.INI, stored without scaling. Absolute values use signed wrapping negation. With primary and secondary separations a and b, and threshold s:

• If abs(a) < s, it requests a sidestep only when abs(b) > s / 3, using the sign of a.
• Otherwise, if abs(b) < s, it requests a sidestep only when abs(a) > s / 2, using the sign of b.

Division truncates toward zero. A negative chosen separation requests right; zero or positive requests left. Both use duration one. The helper returns one after making that request, without using the movement routine’s numeric return, and zero when it makes no request.

Selected-player maintenance is skipped when its retained entry-inhibition value is nonzero. Player initialization clears this value. Player activation replaces it with the activation operation’s result, so initialization does not make it permanently zero. This gate does not inhibit nonplayer maintenance.

The target/perception prepass returns false for the selected player before nonplayer perception processing. For a nonplayer actor, it returns false when combat flag mask 0x04 is clear or the target is absent. When maintenance reaches a combat record, it restores attribute 1 from attribute 119 before processing messages. The nonplayer decision stage runs only for death/state selector 6 and an actor that is not dead. This stage can select targets and consume random values.

After walk-map or free-node admission, the nonplayer perception prepass samples visibility at twice the combat far range. The combat record retains a signed lost-sight timer and a lost-sight routing flag, both cleared by combat construction. The delay is [misc] node_timer from COMBAT.INI, stored without scaling.

When visibility is absent, the timer is compared with the delay before any increment. Only a timer strictly greater than the delay enters routed pursuit. At or below the delay, the timer adds the shared nominal tick count with 32-bit wrapping and the prepass returns false. Crossing the delay during that addition therefore takes effect on a later pass.

Above the delay, a zero lost-sight flag permits a coordination-peer lookup. A successful lookup sends message 0xD002 to that peer and sets the actor’s coordination selection state to zero. The lost-sight flag is then set to one, point navigation is requested toward the target’s current query position with zero tolerance, and the prepass returns true. This path does not increment or clear the timer. A nonzero flag skips the peer lookup on later pursuit passes.

Visible targets reset the timer to zero. If the lost-sight flag is nonzero, reacquisition restores lifecycle selector six, clears the flag, releases held next/current nodes, sets coordination selection state to one, and clears all walk-node reservation bytes, in that order. The prepass then returns false.

Selected-player combat processing uses the attack/defence executor state as its phase value. This state is separate from both the cooldown and the retained combat allocation index. After message processing, phase zero with a nonzero action selector resets the action selector and both retained action indices to -1. An action selector of zero leaves all three values unchanged at this step.

It then calls the first maintenance helper followed by the second, both with action -1. With phase zero and argument -1, the first helper returns false without invoking other services or changing actor or combat state. With the combat record in its freshly initialized state, the second helper also returns false without invoking other services or changing actor or combat state.

The selected player’s drawing or sheathing state suspends action and cooldown maintenance. Otherwise a nonzero cooldown decreases by the shared nominal tick count, saturating at zero. With zero cooldown, action -1 does no attack work; actions 0 through 6 enter attack processing. Other action values reset to -1.

Attack-processing admission

Attack processing requires a combat record and an action other than -1 or nine. The animation admission query reads the animation state’s unsigned reverse-playback byte. It must return zero, and combat flag 0x01 must be set. Only then does processing query the current attack’s active collision window. A true result skips the extended-window query. A false result consults the extended window instead. If either window admits the attack, processing sets combat flag 0x20 before traversing either collision-candidate list. Empty candidate lists leave that flag set.

The active collision window uses the signed animation command cursor and the current motion’s first_collide_frame and collide_duration. It includes the start and excludes the end: start <= cursor < start + duration. The end uses signed 32-bit wrapping addition. A cursor before the start rejects the window without querying duration.

The extended window first requires a nonzero duration. It then requires cursor >= start + duration, using the same wrapping end calculation, and combat flag 0x20 clear. It reads that flag only after the cursor comparison succeeds. Negative durations receive no separate rejection. Both windows use the command cursor, not the displayed model frame or frame-progress byte.

Combat candidate dispatch

Attack processing scans its ordered actor candidates, skipping empty entries. For a candidate with a combat record, it first runs that candidate’s defence query against the attacker. A nonzero defence result skips the contact query. Otherwise it queries contact from the attacker to the candidate. A zero contact result continues the scan.

On the first nonzero contact result, it clears the attacker’s combat flag masks 0x01 and 0x02, emits message 0xd001 from the attacker to the candidate, and requests the attacker’s combat taunt category 3, in that order. It then returns without scanning later actor or static candidates.

A candidate without a combat record skips the defence query. The contact query from the attacker to it must succeed and the candidate must not be dead (IsDead). An attacker with nonzero attribute 97 that neither holds a weapon nor has combat flag four then returns without scanning later candidates and without any response. Otherwise the same impact response as for an actor-owned face runs: the attacker’s attribute-86 effect at volume zero and pitch offset rnd(128) * 16 - 1024 Hz, then, for a candidate with nonzero health, negative attack damage and a death dispatch with selector zero below one. Attack processing then clears the attacker’s combat flag masks 0x01 and 0x02 and returns without scanning later candidates.

Unowned static weapon contact

After actor candidates, attack processing visits retained face-query models in candidate order. Each model receives the retained weapon tip followed by the base as segment endpoints, with query option zero. Results zero and minus one are misses; every other result admits the unowned-model impact response.

Query mode zero scans authored faces after model and face-group admission. Mode one returns zero when a face-group bound admits the segment, without scanning its faces. Mode two returns zero after model-radius admission, without visiting face groups. These modes are separate from the shared polygon-sidedness flag. Its initial stored value is enabled, and initialization also enables it. The temporary query scopes which disable it restore it to enabled before returning. The weapon contact caller does not assign the flag. With sidedness enabled, the face query rejects a segment whose start lies more than four map units behind the authored face plane.

A model without an actor owner uses installed [misc] sword_clank_1, with volume zero and pitch offset rnd(128) * 16 - 1024 Hz, positioned on the attacker. Candidate type exactly one repeats the impact sound with a separate random draw. Other candidate types request one sound. The scan continues to later candidates and leaves attack intent set. Models with actor owners use the actor-response path separately from this unowned-model response.

Actor-owned face contact

An actor-owned face candidate still receives the model segment query, but the result does not gate its actor contact test. A successful actor contact must also pass the target rejection check. For attackers with attribute 97 equal to zero, this admits the impact response directly. Other attackers require either the weapon-holding predicate or combat flag four.

The response requests the attacker’s attribute-86 effect at volume zero and pitch offset rnd(128) * 16 - 1024 Hz, then flushes the sound request. A target with nonzero health receives negative attack damage, followed by a health read. A result below one dispatches its death response with selector zero. Zero health skips damage and death dispatch. Processing continues to later face candidates and retains attack intent, including after a successful response.

Contact damage and nonplayer health

Contact damage reads the receiver’s retained attack slot and motion selector. A negative attack slot returns zero; otherwise the selected motion’s signed damage value is returned without additional arithmetic.

The nonplayer additive health routine first rejects a nonzero attribute 120. If attribute 97 is nonzero, it also requires either the weapon-holding predicate or combat flag four. These checks precede the health write. An admitted change adds the signed change to the unsigned health byte with signed 32-bit wrapping, then clamps the result to zero through 255. This additive routine does not dispatch death itself; the contact caller reads health and owns that dispatch.

Combat hit-reaction admission and animation

A nonplayer hit receiver requires either attribute 102 equal to zero or its value equal to the sender’s attribute 23. A mismatch skips displacement, animation and damage. The selected player bypasses this outer admission test.

An admitted reaction displaces the receiver relative to the sender using the same 3000-unit horizontal translation as the block-message response. It leaves the sender’s position unchanged. For the selected player, a nonzero retained death-animation override then returns before weapon queries, animation or damage.

A nonplayer reaction starts animation group 117 without querying weapon state. The selected player first tests weapon holding, then combat stance only when not holding a weapon. Either predicate selects group 117 on an even world-loop counter or 118 on an odd counter. Otherwise it queries availability of group 119. When available, the receiver-to-sender forward-orientation check selects 119 for a hit in front or 120 otherwise. When unavailable, world-loop parity selects group 132 or 133 instead. All these starters receive loop argument zero.

After animation, damage still requires attribute 102 to be zero or to match the sender’s attribute 23, including for the selected player. A selected-player reaction admitted only by identity therefore animates without applying this damage response. After admitted damage returns, sender attribute 23 equal to 75 requests the sender’s ordinary weapon-restoration service.

Combat direct-damage response

The 0xd005 response helper first displaces the receiver relative to the sender using the 3000-unit horizontal translation. For the selected player, a nonzero retained death-animation override then returns before weapon queries, animation or damage.

A nonplayer receiver starts animation group 117. The selected player tests weapon holding, then combat stance only when not holding a weapon. Either predicate selects group 117 on even world-loop parity or 118 on odd parity; otherwise parity selects group 132 or 133. All starters receive loop argument zero. This response does not query group 119 or forward orientation.

After animation, an enabled selected-player damage-suppression flag skips the health response for the selected player. Other receivers continue regardless of that flag. The response negates the sender’s unsigned attribute 96 and passes that signed change to generic additive health with mode zero, then reads the receiver’s health. Health below one requests receiver taunt category six only for a nonplayer receiver, then invokes the combat death service with selector zero for either identity. Nonfatal health skips taunt and death dispatch.

Combat hit-response damage scaling

The admitted combat hit response reads the attacker’s retained strength and current-motion damage, then the receiver’s retained armor. Compute the product (strength + 100) * damage, then divide it by 100 using signed truncation toward zero. Call that quotient scaled. The health change is -(scaled - (scaled * armor) / 100), with the armor division also truncating toward zero. Integer additions, multiplications, subtractions and negation wrap at 32 bits. No separate strength, damage or armor clamp occurs here.

The response passes this signed change to generic additive health with mode zero, then reads the receiver’s health. Health below one requests receiver taunt category six, followed by attacker taunt category seven. It then reads the attacker’s current motion kind and invokes the receiver’s combat death service with selector zero for kind zero, or selector one for any nonzero kind. Nonfatal health skips these taunts, the motion-kind read and death dispatch.

Health native routing

SetHealth(receiver, value) first raises the selected player’s shared HUD feedback timer to 25 when it is below 26. It computes value - current_health with signed 32-bit wrapping and passes that delta through the generic health-with-death admission service, including for the selected player.

AdjustHealth(receiver, change, mode) performs the same early selected-player feedback update. For the selected player, mode zero directly invokes additive health; every nonzero mode directly invokes death-owning health. These direct selected-player calls bypass generic attribute admission. Their source actor is the retained native-command source described below, except that a source equal to the health receiver is passed as absent.

For other receivers, only mode one selects generic health-with-death admission; all other mode values select generic additive-health admission. These generic services apply their attribute gates before forwarding selected receivers or changing nonplayer health. The early native feedback update remains visible when a later admission rejects the health change.

Both generic services reject nonzero attribute 120 before any weapon or combat query. With nonzero attribute 97, they first test weapon holding. Only when that is false do they read combat flag four. A missing combat record supplies a clear flag. The receiver is admitted when either test succeeds; otherwise it is left unchanged. An admitted selected receiver forwards to the corresponding selected health service with no source actor.

Retained health source context

The ordinary entry/task/main interpreter entry establishes its executing actor as the shared native-command source before entry continuation or the existing-task gate. It establishes this source even when an unpaused task prevents the main body. The separate task-actor update uses the same interpreter entry.

The alternate entry/main path selected by script-control mask 0x04 does not replace that source actor. It retains the source from the previous assigning entry while bypassing the existing-task pass. Both entry paths capture the current shell-execution context before interpreting entry work.

AdjustHealth reads this retained source independently of the receiving actor. For a selected-player receiver, identity equality converts the source to null; a different retained actor remains the source. The source is therefore not recomputed from an object-targeted health receiver or from the actor entering the alternate main path.

Selected-player additive health

Selected-player initialization clears hit inhibition, sets session maximum health to 100 and copies the actor’s current health byte into retained displayed health.

The selected-player additive routine returns immediately when hit inhibition is active. Otherwise it sets a feedback timer below 50 to 25, adds the signed change to current health with signed 32-bit wrapping, and clamps the result to zero through the session maximum health. It writes the health byte first. A negative change requests ordered taunt category two followed by the damage-reaction service, even when the resulting health is zero. Retained displayed health is written after these services return; both services observe the previous displayed-health value. Category two uses the in-order taunt scan and bypasses target-distance and clock-period gates.

The reaction service suppresses its work when either current or pending animation is group 73, 74, 117, 118, 132 or 133. Otherwise it draws random parity and tests the weapon-holding predicate. With that predicate false, even parity selects group 133 and odd parity selects 132. With it true, even selects 118 and odd selects 117. The selected animation starts before the reaction’s action and motion follow-up services.

The action follow-up runs only for the selected player in living state 15 with its inhibition flag clear. Before its transition service, it sets living state 17 and clears its retained ledge-support actor reference, including when the transition is subsequently blocked. If the transition leaves living state nonzero, it clears the three directional state bytes afterward. Other receivers and living states leave this state unchanged. The motion follow-up calls its destruction service only when the receiver has a rope attachment. Without that attachment it does nothing.

Player initialization clears the separate action-inhibition byte. Ledge entry from living state zero requests state 19 and runs the transition. If a nonzero living state remains, it clears the three directional bytes and sets action inhibition to 16. This byte is separate from hit rejection and combat-decision inhibition.

The state-17 transition requests group 56 and clears living state when the receiver is the selected player, attribute 105 is not one, the torch-burning counter is zero, and neither current group 149 nor 150 blocks it. Those groups block only while animation is enabled and shell context is clear. The animation request precedes the living-state clear. Other combinations retain state 17.

The admitted state-17 transition sets the retained action-transition counter to six. Ordinary actor updates leave a zero counter unchanged. For a nonzero counter, if either of the first two directional bytes is zero and the signed counter is less than three, the counter clears immediately. This test does not depend on living state. Otherwise the update clears the high bit of both bytes, subtracts the low byte of the shared tick count with byte wrapping, and clamps a negative signed-byte result to zero.

Replenishing health

ReplenishHealth takes no arguments. If the receiver’s health byte is at least 100, it returns zero without changing health or feedback. Otherwise it sets the health byte to 100 and returns one. For the selected player, the change first raises the shared HUD health-feedback timer to 25 when it is at most 25; larger timers remain unchanged. This command does not write retained displayed health or invoke additive-health inhibition, hurt reactions or death services.

Rope construction and swing

Loading a map builds one rope per MPRP record, only when SYSTEM.INI ropes_load is set. At most 255 ropes exist; another is a fatal error. A rope retains a link array and an attachment list and joins the head of the rope list.

Constructor inputs, from the record: the link model is rope_model and the optional end model static_model (an empty name is none); the base position; length links (an i16); the swing maximum amplitude; the speed rate, where a value below 1 becomes 199; and the type byte. An end model sets bit 0x10 of the type byte. Bit 0x20 starts the live amplitude at the maximum (otherwise 0). Heading angle_y and the three swing sound effects at 0x34–0x3C are stored on the rope. A nonzero word at 0x44 lowers the base Y by the link length times length, plus 256 times an engine constant. A link’s length is a fixed-point value taken from its model record. Link i records its position along the rope as (link length / 2 + i × link length) >> 8 and its extent as link length >> 8.

Each update, for ropes whose active word (set to 1 at construction) is 1, the amplitude is clamped to 0..maximum. With type bits 0x4 and 0x8 clear and a nonzero amplitude, the phase advances by speed × 0x40 × frame scale >> 8 and the step angle is sine[(phase >> 8) & 0x7FF] × amplitude >> 9. A zero amplitude gives step angle 0. Attached actors playing animation 0x52 move one node toward the base, and 0x53 one node down while the limit routine allows it; each such step also sets the amplitude to 2 and the phase to 0 when the amplitude and the rope’s word at offset 0x62 are zero. The integer sine table holds, for i in 0..1023, trunc(sin(i × π / 1024) × 65536), with the entry at 2048 − i negated and the entry at 1024 zero.

Placement runs from the map render list. Link 0 sits at the rope position, yawed by −angle_y & 0x7FF and pitched by −(amplitude >> 8) & 0x7FF. Link i ≥ 1 sits at the previous link position plus the previous link’s matrix applied to (0, link length, 0), and is yawed the same way and pitched by −(sum of the step angles of links 1..i−1 >> 8) & 0x7FF, so link 1 has pitch 0 and an unswinging rope hangs straight. Positions are stored as single-precision values divided by 256. An actor attached to node i is placed on that link position. Each placement then offsets the actor by its hand: the vector (0, −hand Y, −hand Z) of the same grip vertex, rotated by the actor’s own orientation (heading, pitch, roll 0), is added to the actor’s position, so the hand rests on the link. The Y component is skipped while the actor plays group 0x54 with the animation record byte +0x11 below 3.

Rope attachment

Each ordinary actor update of an actor whose movement profile enables the rope check runs an attachment test before ordinary movement. When the test reports true the ordinary movement and combat stages are skipped for that update. The test is false for every actor except the selected player, and false while the player is holding a weapon (see IsHoldingWeapon).

For the selected player the test returns true without further work when it already has an attachment. It returns false when its directional state bytes 0x1B2 and 0x1B3 are both zero, and when byte 0xC1 is zero while the actor has no animation record or that record’s word at offset 0x161 is zero. A nonzero rope countdown (byte 0x1B0) then decrements by the low byte of the shared tick count; when it would reach zero, the stored rope identifier (byte 0x1AF) and the countdown both clear. The rope identifier is the byte at rope offset 0xC, so a rope the player just left is skipped until the countdown expires.

Ropes are tried in list order, head first. A rope is a candidate when it is not skipped by the identifier rule, it has a link array and more than one link, and it has a contact sphere list. Contact is decided by one of two tests:

• With type bit 0x1 clear, any overlap between the player’s body spheres and the rope’s contact spheres.
• With type bit 0x1 set, the absolute heading difference (the smaller of the differences from the rope heading and from the rope heading plus 0x400, over the 0..0x7FF circle) must not exceed SYSTEM.INI rope_attach_angle masked with 0x3FF (512 as shipped), and the same sphere overlap must hold.

The player’s spheres are its RAVC records (flag 2 always, flag 4 only while the actor’s current animation group pair matches the record) followed, unless attribute 56 is nonzero, by its ordinary collision shape spheres; each center is rotated by the actor orientation and added to its position. At most 128 take part. The rope’s spheres are the records of its own sphere list (11 bytes each: flags, a 16-bit position triple and radius, each >> 16 << 8), translated by the rope position, at most 128. Two spheres overlap when the rounded three-axis distance between their centers is less than the sum of their radii. Contact also records the lowest rope sphere index that touched.

On contact the actor requests animation group 0x54, then attaches (below). For the selected player the rope’s type bit 0x4 clears afterwards and a retained flag is set to one.

Attach removes any attachment the actor already has (the removal above), allocates a 20-byte node, links it at the head of the rope’s attachment list, stores the actor in the node and the node in the actor, copies the rope identifier into the actor and clears the countdown. The requested link index is the lowest touching sphere index, clamped to [0, link count − 1], then replaced by the link nearest to the actor’s hand height: starting at index − 8 (floor 0), the link whose stored Y (a single-precision value) is at or below the target height and closest to it wins. The hand point is grip vertex 0 (the RAEX grip0 vertex) of the first ShowFrame of animation group 79, as the integer Q8 model vertex. The target is (hand Y + actor Y + 2 × link length − 1) >> 8, the link length in Q8 as stored on the rope. When its distance from the floor probe is less than the actor height limit plus the vertex’s absolute Y, it becomes the floor probe minus that limit. With no group 79 frame the requested index stands. The node stores that chosen link index.

node stores that chosen link index.

Then, with type bit 0x1 clear the rope heading becomes the actor heading; with it set the actor heading adds the signed heading difference selected above. When either of the actor’s directional bytes 0x1B2 and 0x1B3 exceeds one, the rope word at offset 0x6A becomes zero while actor byte 0x1CB is 3 or 7 and 0x40000 otherwise, and the rope amplitude becomes (d / 1000) × (link count / link index) rounded, with d the rounded planar distance of the actor’s last step in Q8 and the integer division of d by 1000 truncated, and the rope word at offset 0x62 clears. Finally bytes 0x1B1 through 0x1B4 of the actor clear, and animation group 0x54 is requested when it is not already current.

Rope control while attached

An actor attached to a rope skips the ordinary movement and combat stages (see Rope attachment). The selected player’s movement dispatch has a rope branch that runs while it is attached. Keys are the KEYS.INI bindings: Up, Down, Left, Right, A (key_a), B (key_b, the jump key) and C (key_c, the view key).

• Idle. When the actor holds a weapon, or neither Up nor Down is held, the branch requests group 6 (the idle-rope entry of the named group table).
• Jump release. B is latched on attach: the latch stays set while B is held and clears on an update with B up. With the latch clear and B held, the branch removes the attachment (the removal with its detach motion), runs the ordinary jump entry (which, with the rope countdown now nonzero, requests group 85 and sets the second directional-state byte to 24), clears the heading-turn rate below and sets the latch. Damage and a world change also remove the attachment.
• Climb. Without a held weapon and with C up, Up runs the climb-up helper and otherwise Down runs the climb-down helper. Climb up does nothing unless the attachment’s node index is at least 2; it requests group 82 when the current group is not 82 and returns true, otherwise it requests group 82 again while the animation record’s byte +0x0a is zero and returns whether byte +0x0b is nonzero. Climb down asks the hand-height link choice for node index + 1; it does nothing unless the result is greater than the current index, requests group 83 and returns true when the group was not already 83, and otherwise returns whether byte +0x0b is nonzero. Each update the rope owner reads the current group: group 82 moves the attachment one node toward the base when the shared tick count is nonzero, and group 83 one node down while the limit routine allows it, and either step sets the amplitude to 2 and the phase to zero when both the amplitude and the pending push (the word at rope offset 0x62) are zero. The selected player’s ordinary update also requests group 83 for Down and else group 82 for Up while attached and C is up.
• Turn. A nonzero heading-turn rate adds (rate >> 4) × tick scale >> 8 to the actor heading (mod 2048) each update and accumulates the step; the rate clears once the accumulated total exceeds the rate in magnitude. With a zero rate and A held, a rope whose amplitude is below 5 either (type bit 0x1 set) starts a turn of rate 1024 for Left or −1024 for Right with the accumulated total cleared, or (bit clear) adds Right × tick scale >> 8 − Left × tick scale >> 8 to the heading.
• Pump. With C and A up, the pump service runs on the attached rope unless its type bit 0x8 is set. With neither Left nor Right held it clears the pending push. Otherwise, while the amplitude is zero it adds 3 to the pending push, sets the amplitude to 2 and, with d the absolute heading difference between the actor and the rope heading, sets the phase (rope offset 0x6A) to 0x40000 for Left or zero for Right when d is below 16, and the opposite when it is not. While the amplitude is nonzero it takes the rope’s direction byte (offset 0x38), flipped when type bit 0x1 is set and d exceeds 16, and adds 3 to the pending push for Left when the byte is 1 and for Right when it is 0; the other key subtracts 3 while the amplitude exceeds 2.

While an attachment is placed on its node during the chain update, a selected player whose pending group is unset (or is group 79) and who holds neither Up nor Down requests group 80 when the rope’s direction byte is nonzero. With that byte zero it requests group 81 when its pitch is nonzero.

Rope amplitude updates

Each chain update ends by passing the sum t of the link step angles to the amplitude service, which keeps the previous sum t'. A zero crossing (t ≥ 0 with t' < 0, t < 0 with t' ≥ 0, or both zero) runs two things. First, when the rope has attachments and L = maximum / 4 exceeds 2, it plays a swing sound by amplitude a: sound 3 when a ≥ 3L, else sound 2 when a ≥ 2L, else sound 1 when a ≥ L, each only when its effect number is nonzero. Second, with u = maximum / 5 and p the pending push (the word at offset 0x62), it adjusts the amplitude and the push by one step:

• p > 0: the step is 5 when p ≥ 5 and p > 4u, else 4 when p ≥ 4 and p > 3u, else 2 when p ≥ 2 and p > 2u, else 1. The amplitude gains the step and the push loses it.
• p < 0, with n = −p: the step is 1 when n ≤ 3u and (n > 2 or n ≤ 2u), 2 when n ≤ 3u otherwise, 4 when n > 3u and n ≤ 4u, and 5 when n > 4u. The amplitude loses the step and the push gains it.
• p = 0 and t or t' nonzero: the amplitude falls by 5 when it exceeds 4u, else 4 above 3u, else 2 above 2u, else 1 while nonzero.

After either branch the direction byte (offset 0x38, copied to 0x39) is 0 when t ≠ 0 and t' < t, and 1 otherwise, and t' becomes t. The amplitude is then clamped to 0..maximum by the next update.

Rope update order

Each world-loop iteration builds the map render lists first, which places every rope’s links and attached actors and runs each rope’s amplitude service, then runs the rope update (swing step and attachment climbs), then the shell scripts, then the ordinary actors, whose update runs the attachment test and the attached controls.

Rope attachment removal

Ropes own doubly linked lists of attachment nodes. Each node retains its actor, rope position and motion value. The actor retains the node identity. Owner lookup scans the rope list and each attachment list by node identity; an absent owner prevents removal.

Removal reconnects both neighboring nodes and replaces the rope’s head when the removed node is the head. Removing the only attachment leaves the owner with an empty attachment list. With a retained actor whose attachment is either this node or null, removal applies detach motion, clears the actor’s attachment and pitch, and sets its rope countdown to 24 before releasing the node. If the actor instead names another attachment, those actor writes are skipped. The removed node is released after the list and eligible actor updates.

The detach motion is the actor’s forward speed word, which queued motion 24 turns into a horizontal move of |speed| × frame scale >> 8 Q8 units per update, forward at the actor heading for a nonnegative word and backward (heading plus 1024) for a negative one. With j the SYSTEM.INI rope_jump_add shifted left by eight (4608 as shipped) and m the node’s motion value (the planar speed the chain update measured between the node’s previous and new link position, in Q8, negated when the rope’s direction byte is zero): when the rope amplitude is below 6 and |m| is below frame scale × 0x1800 >> 8, the word is zero, except that for the selected player Up sets it to j and Down to −j. Otherwise, with the direction byte flipped when type bit 0x1 is set and the actor’s heading differs from the rope heading by more than 16, a byte of 1 sets the word to j + (|m| << 8) / frame scale and a byte of 0 sets it to −j − (|m| << 8) / frame scale.

Destroying an entire rope uses a separate path. It unlinks the rope from the rope list, walks and releases its attachment nodes, and clears each retained actor’s attachment link, even when that link names a different attachment. It does not invoke attachment detach motion or change actor pitch and rope countdown. Attachment nodes are released in list order, followed by the optional auxiliary record, optional end-model record and the rope itself. A null rope does nothing.

For the detach direction branch, the rope’s angle flag enables a heading test. The signed heading difference wraps over 2048 units. An absolute difference strictly greater than 16 flips the rope’s direction bit for that detach.

Selected-player death-owning health mode

The death-owning health service is separate from selected additive health. Hit inhibition rejects it before any service. Otherwise, a health-feedback timer below 50 is set to 25 before action cleanup or the health write. For a negative change, action reset and rope detach run before the actor health write. The service then clamps the wrapping sum to the session maximum and zero, and publishes actor and retained displayed health before later notification.

When health becomes zero and the session death-suppression flag is clear, it requests taunt category six, enables hit inhibition, clears the retained death-progress word, captures the selected actor’s local position and sends death notification, which sets its death selector to eight without changing other actor state. An existing controller animation override is preserved. If no override is set, a nonnull source actor’s nonzero attribute 109 supplies it before ordinary death animation selection.

When neither an existing override nor the source supplies a group, underwater state two or four sets the retained death mode to two. Attribute 105 equal to one skips the remaining animation choice. Otherwise, a nonzero fall_flag or current group 114, 116, 130 or 131 sets the override to group 74. With none of those conditions, an unarmed receiver force-starts group 134. A receiver holding a weapon starts group 122 when present, otherwise group 121, then stores death default 124 or 123 respectively and releases its held walk nodes, in that order.

The nonfatal or death-suppressed path instead clears the override, hit inhibition and the retained death-progress word. This word is separate from the controller’s pending action flag. A negative change then requests taunt category two and the damage reaction after health publication. These service orders differ from selected additive health and are not interchangeable.

Selected-player death admission state

IsDead returns true for a selected player with nonzero hit inhibition, or for any receiver whose death selector is eight. The retained death-animation group does not participate in this predicate. The same hit-inhibition flag gates selected-controller death execution, ordinary defence sampling and dead-receiver taunt rejection. It is separate from the retained death-animation group.

Selected-player death animation override

The selected player’s retained controller override stores an animation group identity, not only an active flag. When that override and selected hit inhibition are both nonzero, default-animation selection copies the override group into the actor’s default animation. If the current group already matches, it cancels the pending group, clears the current playback exit marker, and sets its finite loop countdown to 32. This replaces any previous loop countdown without restarting the current frame or resetting its command cursor. Otherwise it force-starts the override group. This branch bypasses ordinary default-animation selection.

Selected-player death controller

Hit inhibition admits the selected death controller after the ordinary preliminary controller countdowns. If the retained animation override is zero, the controller assigns group 122 while the actor holds a weapon, or group 134 otherwise. A nonzero retained group bypasses the weapon query.

Every admitted call force-requests the retained group with modifier zero before adding the nominal-tick increment to the retained death-progress word. The addition wraps at 32 bits; the starter observes the previous progress value. Only death modes one and two perform environmental effect updates. Zero and other mode values return after progress accumulation. The player initializer clears both death mode and progress to zero. These words are separate from the controller pending-action flag and preliminary countdowns.

For a selected player with hit inhibition, attribute 105 equal to one and death mode two, the world loop exits with outcome 5000 only when signed death progress is strictly greater than 12. Progress 12 does not exit. This branch bypasses the ordinary retained-group animation-completion comparison.

Otherwise, inhibited selected-player death completes only while the current animation group equals the retained override. For override groups 13 and 74, the signed command cursor must be less than or equal to the unsigned wrapping frame-progress byte, anim.real_frame. For other override groups, completion requires that cursor and progress byte differ. This compares command progress with frame progress, not the displayed model frame or finite loop countdown. Completion returns world-loop outcome 5000.

World-loop death exit ordering

The world loop checks death exits after map and separate-object updates, effects, scene and HUD presentation, and fade handling. A pending world transition returns its destination before the falling timeout or selected inhibition checks. The win request is checked after those death exits.

A selected player whose falling byte is zero clears the retained falling elapsed counter. A nonzero falling byte adds the shared nominal-tick increment to that counter, wrapping at 32 bits. When the resulting signed value is strictly greater than the configured falling-death limit, the loop returns outcome 5000. Equality does not exit. This check precedes, and does not require, selected-player hit inhibition. The player initializer clears this counter independently of selected death mode and progress.

The limit is max(player_fall_dead_time, 3) * 12, using signed configuration comparison and 32-bit multiplication. It is measured in nominal ticks, not rendered frames. A pending world transition bypasses the counter update as well as the death checks.

Death completion dispatch

After world-loop outcome 5000, the main dispatcher checks the retained last-save slot. An absent slot opens the book menu with entry context three. An available slot presents a Yes/No request to load the last game, with the retained save description appended to the prompt. No opens the same book-menu context. Yes copies that slot into the pending load selection and selects saved-game loading for the next dispatcher pass.

The dispatcher clears selected-player hit inhibition after the confirmation or book-menu call returns. The saved-game loading pass receives the retained slot, then clears the pending selection and returns the dispatcher to world execution.

Selected death effect admission

Death-controller environmental effects read progress after its nominal-tick increment. Mode one always emits its first effect. It then makes two independent bounded random requests, each with bound progress / 6 + 1 using signed progress and division truncating toward zero; a zero result emits the corresponding additional effect. These random requests remain ordered and independent. A final effect is emitted only when signed progress exceeds 12.

Mode two consumes one raw engine random value. It emits only when the bitwise AND of that value and wrapping progress + 1 is zero. An admitted emission uses one effect variant before signed progress 12 and another from 12 onward. It then requests actor sound 71 before 12 or sound 70 from 12 onward, after a bounded random request of 64 whose result is reduced by 32 for the sound’s signed variation argument. No effect or sound request occurs when the initial bitwise test rejects the call.

The packed descriptors passed to effect construction are:

The low sixteen bits identify the texture; the upper sixteen bits are effect flags. Every selected-death construction supplies zero spread and speed one.

Each emission first computes the camera-relative point described below, then consumes two bounded random requests in X-then-Z order. The unconditional mode-one image uses bound 32 and adds draw * 256 - 4096 to each horizontal coordinate. Every other selected-death image uses bound eight and adds draw * 256 - 1024. Y is the transformed point’s Y plus the receiver’s retained positive Y bounds extent multiplied by 256, plus 1536. These coordinate operations wrap at 32 bits. The extent is the stored bounds record’s positive Y extent, not the actor’s current origin, animation image height or effect texture height. These point and random operations still run when effect construction later finds a disabled or full pool.

The mode-two sound is positioned from the receiver’s ordinary sound query and uses zero volume offset. Its signed variation is passed directly as the playback-rate offset in Hz.

The effect-position helper copies the supplied integer point and preserves its Y coordinate. It subtracts the published current camera X/Z coordinates from the point using signed wrapping 32-bit subtraction, then computes the shared quantized horizontal bearing in 2048 units per turn. Camera height does not participate. With index = (bearing - 1024) & 2047, it adds offset * sine[index] to X and offset * sine[index + 512] to Z. The death controller supplies offset 2048.

Each original X/Z coordinate is converted to single precision before the displacement is added. Each sum is stored in single precision, then converted to an integer by truncating toward zero. The helper returns a shared scratch point and leaves the supplied point unchanged.

Environmental effect animation

World initialization tears down the previous environmental effect pool before creating a pool with [system] max_effects from SYSTEM.INI. Negative configured capacity is clamped to zero. A zero capacity or a nonzero disable_effects setting leaves the pool disabled. An enabled pool starts with every slot free.

Allocation scans the retained pool list from its head and takes the first free slot. It marks that slot active and decrements the free count without moving the slot in the list. Release marks an active slot free and restores the free count, without exceeding capacity. Releasing an already free slot has no effect. Update and drawing traverse the same retained list order.

The type-one effect constructor returns no effect when the pool is disabled or allocation fails. It separates the supplied packed descriptor into upper-16-bit flags and a lower-16-bit texture identity. The resolved texture supplies the target frame as its runtime frame count minus one. Current and reference frames start at zero, and the constructor retains the supplied animation speed.

For zero spread, the constructor subtracts texture_height * 128 from the supplied fixed-point Y coordinate with wrapping 32-bit arithmetic. Position publication then arithmetic-shifts each signed coordinate right by eight bits. This places the effect half its texture height above the supplied point in the engine’s downward-positive Y convention.

The world loop submits environmental effect billboards while building map draw lists, after actor model-position processing and before the object and code-object systems run. It updates effect lifetimes after those systems, before the rain-drop update and rendering the queued scene. Effects created by those later object updates miss the current loop’s billboard submission but participate in its lifetime update. Surviving effects can submit on the next loop. An effect already submitted can expire during the subsequent lifetime update; releasing its slot does not remove the submitted billboard.

The type-one environmental effect updater rejects a disabled effect pool, a null effect, a different effect type or a zero texture descriptor. Otherwise it leaves the current frame unchanged when that frame is -1 or the retained reference frame equals the target frame.

When the reference frame is below the target, the updater adds nominal ticks multiplied by animation speed to the current frame. It keeps the effect alive through equality with the target and expires it only above the target. When the reference frame is above the target, it subtracts the same product and expires only below the target. Multiplication and frame arithmetic wrap at 32 bits; reference, target and expiration comparisons are signed. The retained reference, rather than the current frame, chooses the direction.

Environmental effect frame submission

The enabled pool’s draw traversal runs only when at least one slot is active and walks the retained list in order. Before checking a record’s type or texture, packed flag 0x20000 subtracts nominal_ticks + 2 from its retained whole-map Y coordinate with wrapping 32-bit arithmetic. This changes retained state even when that record does not submit a draw. Disabled or entirely free pools skip the traversal and this position change.

For type-one records, a positive signed texture descriptor admits the draw wrapper. Construction zero-extends the lower sixteen-bit texture identity, so identities with bit fifteen set remain positive. Identity zero skips the wrapper; identity 65535 reaches the wrapper but submits no billboard. Packed flag 0x10000 selects caller scale 90; otherwise the caller scale is 256. The alternate drawing path retains its own fixed geometry scale.

Ordinary type-one effect drawing submits the resolved texture with automatic frame selection, independently of the effect’s retained animation frame. The retained frame still controls effect lifetime. Packed effect flag 0x20000 selects the alternate drawing path, which submits that retained frame explicitly instead. Both paths submit the retained integer position converted to single precision. The alternate path bypasses the ordinary effect metadata lookup.

The ordinary path submits face brightness 255 and geometry scale equal to the draw caller’s integer scale divided by 256. Its default constant alpha is 255. When texture metadata exists, metadata byte two plus one supplies alpha, and metadata byte one is ORed into drawing flags initially set to one. The alternate path submits geometry scale one half, constant alpha 140 and drawing flags 0x201.

The alternate path takes face brightness from the current world’s world_ambientfx value in WORLD.INI. World preparation stores that integer in sixteen bits and replaces a stored zero with 128. World entry publishes it as a signed sixteen-bit value before effect drawing. This scalar is separate from world_ambientrgb and the ordinary effect path’s fixed brightness 255.

The ordinary metadata lookup uses the current map’s FLAT texture attributes, shared with placed flats. It splits the texture identity into the archive and seven-bit image IDs and uses the first matching attribute record. Missing records leave the defaults unchanged.

Both paths use a centered camera-facing quad. Its half extents are the source image width and height multiplied by half the texture scale and geometry scale. Texture-coordinate scale is one. Alpha, face brightness and frame selection remain separate inputs to the shared billboard submission. The source bound uses the same quantized source-image diagonal as centered ordinary flats, multiplied by half the texture scale and geometry scale. Reduced texture allocation dimensions do not determine the bound.

Shared billboard submission transforms the retained center into camera space and tests its source bound before requesting a texture frame. A rejected bound neither requests the image nor appends a draw packet. An accepted bound requests the automatic or explicit frame, binds that frame’s face and vertex sources, and appends the packet in submission order. This image request precedes later polygon processing; it does not require raster coverage or the placed-flat spatial-cell selection.

Scene drawing submits ordinary spatial-list billboards before traversing the environmental effect pool. Accepted effect packets append to the same queue in retained pool order and participate in its shared alpha partition.

For centered billboard geometry, drawing flag 0x20 negates the local X half extent and flag 0x40 negates the local Y half extent before corner generation. These flags reverse the corresponding geometry axis while retaining the same source-image bound. Drawing flag 0x100 becomes queued packet flag 0x10.

Billboard drawing flag 0x200 becomes queued packet flag 0x20, which disables depth writes. Packets without that flag enable depth writes. The alternate effect path therefore tests depth without updating the depth buffer. Its depth comparison remains less-than, as on the ordinary path. Packet flag 0x10 selects an always-pass depth comparison instead.

Both effect paths select point texture filtering and constant alpha. Alpha values at least 254 select source-one/destination-zero blending; lower values select source-alpha/one-minus-source-alpha blending. The constant-color alpha channel retains the low byte of the converted alpha value.

Contact death animation dispatch

A null receiver does nothing. Selector zero first checks for animation group 122 and starts it when available. Otherwise the dispatcher checks group 121 and starts it when available. A nonzero selector goes directly to the group-121 check. Missing groups do not prevent the final death-selector assignment.

After a group starts, a receiver with combat state requests walk-node release and stores its death default as 124 for group 122 or 123 for group 121. Receivers without combat state skip those writes. Every nonnull receiver then receives death selector eight.

Combat death service

The direct-damage and scaled hit responses end a fatal hit with this service; the weapon-contact caller uses the contact death animation dispatch instead. A null receiver does nothing. A selected-player receiver does nothing while the session death-suppression flag is set or hit inhibition is active. The service takes a selector: zero prefers death group 122 when the receiver has it, any other selector or a missing group 121.

With attribute 69 equal to zero, the selected player stores the chosen group as the death-animation override when none is set; it does not start the animation here, the selected death controller does. A nonplayer receiver instead force-starts the group, releases its held walk nodes while storing death default 124 (group 122) or 123 (group 121), sends coordination message 0xd002 from itself to the active-state coordinator when one exists, and clears its close-distance pass counter and coordination selection state. A nonplayer without a combat record faults.

Every receiver then resets its combat action selector to -1. A receiver with death selector eight releases its held walk nodes; any other receiver takes the combat reset: lifecycle selector one (with its response byte cleared when the selector was not already one) and, when the killed flag is set, the script-control hook enabled. The service sets death selector eight, clears combat flag 0x04 and zeroes the close-distance pass counter and coordination selection state. The selected player finally applies health -256 through the death-owning health with no source actor, which enables hit inhibition and ends the world loop once the death animation completes. The death-owning armed branch and the nonplayer death admission also reset the combat action selector to -1 after storing the death default.

Hit-defence response

The candidate’s hit-defence query requires the attacker to have combat state and an action other than -1 or nine. The defender’s pending defence index, the word the attack executor resolves through the four defense slots (written by an ordinary counter and by the selected player’s defence stance), must equal the attacker’s current-motion counter-attack reference. The defender’s attack-slot selector does not take part. The attacker’s defence window must admit processing, and the defender must have combat flag 0x02 set. Only then does the query test contact from attacker to defender.

An admitted contact miss clears defender flag 0x08 and returns zero. Earlier admission failures leave this flag unchanged. A contact hit sets the attacker’s reverse-playback byte to one before playing the defender’s impact sound. It then emits message 0xd000 from defender to attacker, requests defender taunt category 4, clears intent masks 0x01 and 0x02 on the defender followed by the attacker, and toggles defender flag 0x08. It returns one. Other combat flag bits survive.

The impact cue comes from COMBAT.INI section [misc]: sword_clank_1 on an even world-loop counter and sword_clank_2 on an odd counter. It uses one random draw with bound 128 and pitch offset draw * 16 - 1024 Hz. The defender supplies the sound position. Sound dispatch and flushing precede the response message.

Defence contact window

The defence window compares the signed animation command cursor against the current motion’s first_defend_frame and defend_duration. It includes the start and excludes the end: start <= cursor < start + duration. The end uses signed 32-bit wrapping addition. A cursor before the start returns zero without reading the duration. Otherwise the query reads start again, then duration, then the cursor again before comparing the end. Zero and negative durations have no separate admission rule. This query does not read the attack-contact mark or playback direction.

Motion contact selection

A motion whose col_sphere_size is zero uses the range/arc contact path. A nonzero value selects sphere contact. Sphere contact resolves the current motion’s col_vertex through the actor’s model-point query, then subtracts the candidate actor’s local position component by component with signed 32-bit wrapping. The three differences feed the distance query. Contact succeeds only when its signed result is strictly less than the current motion’s col_sphere_size. Equality rejects contact.

Contact orientation

Contact orientation subtracts receiver local position from the supplied point with signed 32-bit wrapping, then shifts each component arithmetically right eight bits. The normalized vector’s Y angle is converted to heading by (1024 - angle) & 2047. The absolute wrapped difference from receiver yaw must be strictly less than the current attack motion’s arc + arc_center, with signed 32-bit wrapping in the sum. The current retained attack slot and motion selector supply both fields. Equality rejects orientation. This threshold differs from the first-motion defence-selection arc interval.

Range/arc motion contact

For a candidate with no combat record or a zero combat radius, the range/arc contact path checks orientation, then range, then elevation. A failed check skips the later checks. Orientation and range accept a nonzero result; elevation must return exactly one. Range uses three-dimensional query-position distance. Range and elevation use the receiver’s retained attack-slot selector.

For a candidate with nonzero combat radius and attribute 126 equal to zero, the path first resolves the candidate’s retained model vertex. It tests orientation against that point before querying horizontal query-position distance. The distance must be strictly between the minimum and maximum ranges of the retained attack slot’s first motion, and strictly less than the candidate’s combat radius. Equality at any of these boundaries rejects contact.

For a candidate with nonzero combat radius and attribute 126 nonzero, the range/arc contact path resolves its retained model vertex, then calls the sphere/segment query. The point coordinates and candidate radius shift arithmetically right eight bits for this query. Both segment endpoints use the same retained combat point of the receiver. The contact path returns the query’s result without converting it to a boolean.

With identical segment endpoints, the sphere/segment query tests the endpoint against the sphere. Each endpoint-minus-center coordinate wraps at signed 32 bits and stores as single precision. The squared components add in extended precision, then their sum stores as single precision and truncates to a signed 32-bit integer. An invalid integer conversion produces the signed minimum value. The radius square and its subtraction of that integer both wrap at 32 bits. A nonnegative signed residual returns one, including equality. A negative residual returns zero because the segment has zero length. Radius sign is not separately rejected.

Equipped-weapon combat endpoints

Drawn-weapon attachment requests use the signed RAEX grip0 and grip1 source vertex indices. Stowed-weapon attachment requests use scabbard0 and scabbard1. Both requests use the actor’s current animation handle and frame. The loader copies these four signed words into the actor before attachment queries.

After selecting an equipped-weapon attachment, an actor with combat state retains two endpoints and the attachment record. The base endpoint is the attachment’s floating position truncated component by component to signed integers. For the tip, the local vector (0, -(weapon_length << 8), 0) uses signed 32-bit wrapping and transforms through the attachment matrix. Each transformed integer component shifts arithmetically right eight bits. That integer adds to the corresponding floating attachment position in extended precision, then truncates to a signed integer without an intermediate single-precision sum store.

An absent attachment clears the retained attachment record and leaves both previous endpoints unchanged. An actor without combat state receives none of these writes. The attribute-126 contact path uses the retained tip for both of its segment endpoints.

Combat messages use 256 queues selected by attribute 125. Queue initialization clears each queue; startup and combat reset both allocate eight entries per queue. New Game and save restoration reset these queues. Actors retain separate byte read cursors. A message contains sender, receiver and code. Reading skips messages addressed to another actor, advancing and wrapping the read cursor. A receiver-zero message is accepted by any actor in that class. Sending a nonzero code writes at the class write cursor, advances and wraps it, then clears the next message code. A zero code does not send a message. The combat message stage consumes at most one addressed message per invocation.

Coordination message 0xd002 uses the receiver’s current combat target; 0xd003 uses the sender’s current combat target. Starting at the ordinary list head, they clear coordination state for each living actor whose target equals that target and whose coordination state is exactly one, excluding the target itself. Traversal continues from each matched actor’s successor without wrapping. A null target skips this scan. Clearing or assigning coordination state also resets the actor’s consecutive close-distance counter. After the scan, 0xd002 assigns the receiver coordination state one and aggression 50; 0xd003 assigns those values to the sender. These assignments still occur with a null target. Neither message changes the selected actor’s combat target. Unrecognized nonzero message codes are consumed without combat effects.

Message 0xd000 clears intent bits 0x01 and 0x02 on the receiver, then on the sender. It next displaces the sender horizontally relative to the receiver with a movement amount of 3000. This operation writes position, not actor heading. A null actor skips the displacement. The bearing uses the moving actor’s local X/Z minus the other actor’s local X/Z, with signed 32-bit wrapping. The translation heading is zero on positive Z, 1536 on positive X, 1024 on negative Z and 512 on negative X. The translation uses the original sine and cosine tables, stores the old coordinate and the final sum as single precision, and truncates the final sum toward zero. Y, actor angles and transform matrices are unchanged; this helper does not register a deferred map update.

After displacement, handoff runs only when the receiver’s coordination state is zero, the receiver is not the selected player, and the receiver’s death query returns zero. It searches from the ordinary list head for the first actor other than the sender that has combat state, a nonnull target, death selector other than eight and coordination state exactly one. A match receives message 0xd003 from the receiver. Without a match, the receiver’s coordination state becomes one, resetting its consecutive close-distance counter. This fallback does not assign aggression 50.

Message 0xd001 clears receiver intent bits before sender intent bits. If receiver attribute 97 is nonzero, it tests weapon holding, then combat stance only when not holding a weapon. When both tests are false, response processing returns after the intent clears.

An admitted response draws a random value with bound 128 and requests the receiver’s attribute-86 positional effect with volume zero and pitch draw * 16 - 1024. It completes the positional sound request, requests receiver taunt category two, and reads the sender’s combat action. Sender action eight requests receiver weapon cleanup before the hit-reaction service runs with receiver then sender.

After the reaction returns, receiver action other than minus one or nine resets the sender’s action to minus one. The receiver’s coordination state is then read. State zero, nonselected identity and a zero death query admit the same ordered coordinator search and fallback as the block response. The search excludes the sender. A match receives 0xd003 from the receiver; without a match, the receiver receives coordination state one without assigning aggression 50.

The ordinary 0xd005 response draws with bound 128, requests the attribute-86 positional effect with volume zero and pitch draw * 16 - 1024, completes the positional sound request, requests receiver taunt category two, then invokes the direct-damage response with receiver followed by sender. After that returns, coordination state zero and nonselected identity admit the ordinary coordinator search excluding the sender. Unlike block and hit messages, this tail does not query death. A match receives 0xd003 from the receiver; no match assigns receiver coordination one without assigning aggression 50. This message does not clear either actor’s intent bits.

Messages 0xd000, 0xd001 and 0xd005 consume their addressed message before performing response work. Message 0xd001 also clears the receiver’s intent bits before the sender’s. Message 0xd005 does not perform those intent clears.

Ordinary entry processing is suppressed by an unpaused blocking slot whose call operand address is at or before the saved entry cursor. This test is separate from the later main-body blocking test and from direct interrupt invocation.

Value Modes

The same opcode byte is interpreted differently depending on the calling context. There is no separate addressing-mode byte — the calling instruction determines how trailing bytes are consumed.

The number of trailing bytes consumed after an opcode depends on both the opcode and the current value mode. See Operand Encoding for per-opcode details.

Bytecode Encoding

Opcode Table

All integers are little-endian. The VM reads a leading opcode byte and dispatches. Unrecognized bytes are fatal.

The typed decoder leaves unimplemented opcode encodings explicit rather than interpreting them as successful operations.

Operand Encoding

Flag (0x06) and LocalVar (0x0A) consume different trailing bytes depending on value mode:

Flag (0x06)

LocalVar (0x0A)

ObjectDot (0x14)

Conditional updates write the adjusted value before the comparison and compare that adjusted value. Both sides of every comparison are evaluated, including their updates and function calls.

In PARAMETER mode, NumericAlt consumes four bytes but returns the unsigned low 16 bits. A String parameter consumes four bytes but uses the low byte as its actor-local string index.

Native parameters use numeric, global flag, local variable, string, or object-property operands. Native calls are value expressions outside PARAMETER mode; PARAMETER dispatch does not evaluate nested native calls.

Object-targeted native calls evaluate local-variable and property operands against the receiving actor. Native string parameters instead use the retained native-command source described under Retained health source context. Normal interpreter entry establishes that source before entry continuation and existing-task admission. The script-control mask 0x04 alternate path retains the previous source, including its string table. A string parameter therefore need not use either the native receiver’s table or the alternate path’s executing actor’s table.

A routed initial call preserves the retained source’s string table. A later normal interpreter entry on the receiving actor establishes that receiver as the source before reevaluating its active task’s string indices. The stored task operand location remains in the calling actor’s bytecode.

Object Name Encoding

Used by opcodes 0x0F, 0x10, 0x14, 0x19, 0x1A. A leading byte selects the object target:

Named object lookup compares bytes with ASCII letters A–Z folded to lowercase. It searches registered object namespace names, rather than actor script names. The registry orders entries by their signed 16-bit runtime object identifier; lookup returns the first matching name. Registering an identifier already in that registry does not add another entry.

Runtime object identifiers

Runtime identifiers are separate from the MPOB record’s object id. The reusable actor pool has capacity max(10, SYSTEM.INI [system] max_active_objects). An allocation uses the first free pool slot and initially assigns its zero-based index plus three as the actor’s 16-bit identifier.

World object loading resets its identifier counter to the pool capacity plus three. It visits MPOB records in file order. Types two and six use separate object paths. Each other record creates an ordinary actor. A nonzero activation flag allocates from the reusable pool and increments the counter once; a zero flag allocates outside that pool. The ordinary actor path then increments the counter and assigns its low 16 bits as the actor identifier before loading its script and registering its namespace.

Objects created after world loading by shoot, shootPlayer or DragonBreath are allocated as standalone records rather than from the reusable actor pool. Their runtime identifier is zero. If the installed script supplies an object namespace, creation registers that namespace under identifier zero; repeated registrations of the same identifier retain the first entry.

CYRUS and GREMLIN player instances load independently of MPOB placements. Each uses identifier one; the initial player selector chooses CYRUS. The camera instance loads CAMERA independently of MPOB and uses identifier two. Fresh world loading creates and registers ordinary MPOB actors first, followed by CYRUS, GREMLIN and CAMERA. Each player role is temporarily selected during its own initialization. After GREMLIN initialization, world setup marks it excluded from ordinary object updates and restores CYRUS as the selected player.

Separate map object script state

MPOB types two and six use separate object records rather than ordinary actor records. Script binding uses the same authored instance allocator as ordinary objects: each matching load advances the instance counter and, after the first instance, advances the local-variable pointer by the variable count times four. These objects therefore consume their authored local-variable allocation even though they do not consume the ordinary actor identifier counter.

The separate-object update converts each record into a cleared temporary actor and clears its attribute table. It restores the object’s position, script continuations, local-variable and string pointers, and native task-slot state. After processing, it copies position, continuations and task state back to the separate record. Attribute writes in that temporary actor are not copied back. The separate-object traversal runs after ordinary actor traversal and retains its own list membership. Outside editor mode, it maintains the optional light record after script/task dispatch and before copying the temporary actor back to its separate record. This light maintenance also runs when task-system advancement is disabled. Separate records always belong to their position’s 512-unit map cell, regardless of the MPOB activation byte. Loading prepends each record to its cell’s separate list. The cached view-window rebuild appends those lists in the same cell order as ordinary traversal, skipping the four corners. It does not apply the ordinary outer-border attribute filter to separate records.

Initial ordinary motion state

Fresh ordinary allocation clears the complete actor record before applying loader defaults. Its sliding state, falling state, queued-motion state, body response flags and collision-transition flags therefore start at zero. These runtime bytes are separate from the installed attributes and current animation group. The ordinary update invokes queued motion when its state is nonzero, using that state before the falling state when both are present.

Reference Name Encoding

Object-property operands carry a little-endian u16 reference ID after the object encoding. Property reads use the full reference ID to index the global references table loaded from the [refs] section of SOUP386.DEF. The high byte is not discarded. With native validation enabled, a reference outside the table enters the invalid-reference error path.

Local pose properties

pos.vx, pos.vy and pos.vz access the resolved actor’s local position. angle.vx, angle.vy and angle.vz access its local angles. Each property reads or writes the complete 32-bit field selected by its installed descriptor. Player resolves the currently selected player before accessing the field.

These accesses do not substitute an attached pose, normalize angles, recompute matrices or update other actor fields. Each write changes only its selected field; subsequent actor processing performs the usual transform work. Ordinary heading values use 2048 units per turn.

Current animation property

anim.current reads the resolved actor’s current animation group as a signed 16-bit value, extended to the script integer width. It preserves negative values, including the no-current-group value of -1. If the actor has no animation association, the read returns zero. Reading this property neither requests nor advances an animation and does not change actor or animation state.

Torch counter property

torch_timer accesses the resolved actor’s torch-burning counter. Reads return the unsigned byte as a script integer. Writes retain only the low eight bits of the assigned value and change no other actor field. The property access itself does not run torch effects or decrement the counter.

Operators

Arithmetic Operators

Assignments use a terminated list of (value, operator) pairs. The formula loop reads a value (any value-producing opcode in FORMULA mode), then an operator byte, repeating until the terminator.

The formula evaluator accepts only zero and binary operator bytes 1–9. Other operator bytes enter the fatal error path. Division by zero is not checked in software — it raises a CPU divide-by-zero exception caught by the C runtime signal handler.

The ScriptReader and ScriptParser tools interchange multiplication and division bytes. Engine bytecode uses 3 for multiplication and 4 for division.

Comparison Operators

Used in if conditions. Each comparison pairs a LHS value, comparison byte, and RHS value. Ordered comparisons use signed 32-bit integers.

Conjunctions

Multiple comparisons in a single if are chained with conjunction bytes:

Conditions are evaluated left-to-right with no operator precedence — each conjunction folds the running boolean with the next comparison result.

Control Flow

Conditional Branch (If — 0x03)

Evaluates one or more comparisons chained with and/or. If the condition is false, the PC jumps to end_offset (absolute). If true, execution falls through into the inline block.

[0x03]
  repeat:
    [value: LHS mode]
    [u8 comparison]
    [value: RHS mode]
    [u8 conjunction]       // 0 = end, 1 = and, 2 = or
  until conjunction == 0
[u32 end_offset LE]        // false-branch target (absolute)
[block of instructions]    // executed when true; ends at end_offset

Goto (0x04)

Unconditional jump. Sets PC to the u32 target address (absolute).

End (0x05)

Reads a u32 offset relative to the actor’s script base, stores that address as the main continuation, and returns from the current invocation. It also clears pending synchronization state for the actor’s configured group and user channels and releases the current activation reference when it refers to that actor. These notifications do not clear the stored continuation or disable the actor.

When the actor’s script remains eligible and has no blocking task, a later main script stage starts at that continuation. Target zero therefore restarts at the script base on that later invocation, rather than executing again immediately or stopping permanently.

The installed ISLAND FLAG2 script is 61 bytes: four blocking PushAnimation calls request groups/counts (1, 25), (10, 1), (1, 3), (10, 2), followed by End with target zero. Its finite task counts do not make the whole script finite. The authored sequence can repeat while the actor remains eligible.

Gosub / Return (0x11, 0x12)

Gosub stores the address following its target operand in the actor’s single return continuation, then jumps to the target. A later Gosub overwrites that continuation. Return resumes at the stored continuation and restores the actor’s saved script-return byte. It does not pop a stack or clear the saved continuation. Subroutines share actor-local variables.

A fresh actor’s return continuation is null. A Return executed while it is null (installed scripts reach this by entering a subroutine body with End, for example the VILEDOG actor) behaves like Endint: the invocation ends and the actor’s main continuation becomes the script base. The same holds when the Return runs from the entry continuation; the main continuation is reset to the script base there too, unlike Endint, which preserves it. The game continues running; nothing faults.

Endint (0x13)

Resets the active cursor to the script base and returns from the current invocation. Script-entry processing preserves the main continuation while advancing its separate entry cursor.

Function Dispatch

Call Types

Active tasks reevaluate their encoded operands on every task invocation. A task therefore observes changes to locals, global flags, and queried values while it is active. Literal arguments are a special case of this rule.

Native calls evaluate their parameters from the last authored argument to the first. The handler receives the resulting values in authored argument order. This evaluation order also applies when starting or revisiting a task; nested function side effects are observable by earlier arguments.

SOUP386 distinguishes three call types, encoded in the opcode byte:

Self-calls use opcodes 0x00/0x01/0x02. Object-targeted calls use 0x19/0x1A with an additional dispatch-type byte (0x00 = task, 0x01 = multitask, 0x02 = function) when used as a top-level statement. In non-MAIN modes, the dispatch-type byte is absent and the call is always treated as a function.

The runtime function table keeps only each function’s handler; the task, function or multitask keyword in SOUP386.DEF is parsed and discarded. A call therefore runs the handler of whatever function it names, whichever call type the script uses, and a handler that returns zero completes a task or multitask call at once. Shipped scripts use this for FlatAnimate and FlatSound (both return zero) in multitask form.

Object-targeted task dispatch differs from a self task statement. The receiver owns the task slot, and the calling body continues immediately. The self task statement checks the active result and yields when blocking. Both encodings must remain distinguishable even when the explicit object selector resolves to the current actor.

Call Encoding

[u16 func_id LE]     // index into SOUP386.DEF function table
[u8 param_count]     // number of parameters (0 if func_id == 0)
[param_count × value in PARAMETER mode]

Function index 0 is always NullFunction (synthetic; prepended by the parser, not present in SOUP386.DEF). The func_id is multiplied by the function-table entry stride (49 bytes) to index the runtime table.

Parameter Type Overrides

When a Numeric (0x07) or NumericAlt (0x16) opcode appears in PARAMETER mode, the 4-byte value may be reinterpreted based on the calling function:

ACTIVATE and TorchActivate receive the dialogue key as a packed 32-bit numeric value, not a string-table index. Its least significant byte is the first RTX key character. RTX lookup folds ASCII uppercase bytes to lowercase.

Ordinary entry gate

Ordinary entry processing uses the actor’s saved entry continuation, distinct from its main continuation. When the initial main entry offset is zero, the separate entry continuation is absent. A nonzero initial main offset starts main there and initializes the separate entry continuation at the script base. An absent entry continuation makes ordinary entry processing return immediately. Before running it, the engine checks occupied, unpaused blocking task slots. A slot suppresses entry when its stored operand address is less than or equal to the saved entry address. This is an address comparison, not a comparison of offsets relative to each task’s own script. For programs within the same RASC allocation, adding each script’s RASC offset to its local cursor preserves that ordering.

When entry runs, its saved cursor temporarily becomes the interpreter’s active cursor. The resulting cursor is saved back as the entry continuation, and the main continuation is restored. A yielding entry therefore resumes from its saved position. Endint resets that entry continuation to the script base.

TaskStop, TaskPause, and TaskResume

An actor has six task slots shared by its entry and main invocations. Existing-task processing traverses those slots in allocation order, skips paused slots, reevaluates encoded operands, and removes a slot when its handler reports completion. Unpaused blocking slots suppress the subsequent main-body invocation; multitask slots do not. Reissuing a call whose operand address is already in a slot does not execute its handler again. Task labels resolve against the receiving actor’s script base and match the byte immediately after the labelled dispatch opcode. Self task calls store the operand address immediately after their Task or Multitask opcode. Object task calls store the operand address immediately after the embedded dispatch byte following the two-byte object selector. Routing retains that encoded operand location; it does not rebase foreign bytecode into the receiver’s script. TaskStop removes every matching slot and clears its blocking and pause state. TaskPause and TaskResume set and clear the matching slots’ pause state.

The KillMyTasks function takes no arguments and returns zero. It clears all six of the receiver’s task slots at once, whatever their operand addresses, including their blocking and pause state and retained handler scratch, without invoking any handler. It acts immediately, so a task started by a later statement of the same invocation occupies a fresh slot.

The initial task call invokes its native handler, then allocates a slot independently of that handler’s return value. A self blocking task yields after this allocation, even when its first native invocation reports completion. Completion is applied by a later existing-task pass. An object-targeted task allocates on the receiver and the caller continues, including when the selector resolves to the caller itself.

Each active slot has a 16-bit invocation counter. Allocation sets it to one. An eligible existing-task pass computes its elapsed input as the low 32 bits of counter times the current frame scale, shifted right by eight, then increments the counter with 16-bit wrapping. Paused slots do not advance. The initial native call receives elapsed input zero.

Wait, WaitOnTasks, and WaitNonMulti

Wait(duration) stays active while the elapsed input is less than the wrapping 32-bit value duration - 1, compared as signed integers. WaitOnTasks stays active when more than one unpaused slot is occupied. WaitNonMulti stays active when more than one unpaused blocking slot is occupied. These count tests include the current wait slot when it has already been allocated.

Anchor, Yield, and ScriptRV

Anchor stores its operand byte as the actor’s anchor state. Yield retains the following cursor without issuing the End notifications.

ScriptRV reads an expected byte. On mismatch it skips the next five bytes. On a match, a following Return byte advances the cursor by four bytes; a following Gosub saves the current script-return byte before the control instruction runs. Other following instructions remain eligible. Return restores that saved byte.

Group synchronization channels

Actor data byte 29 names the actor’s group channel (1 through 255; zero means none), byte 30 its user channel, and a nonzero byte 43 excludes the actor from its group channel’s rendezvous. Actors join their channel’s member list when they are created. World initialization enables the system and clears every channel’s released value; with the system disabled, or for an actor without a channel or member entry, SyncWithGroup completes immediately.

Each member holds a posted value, initially zero. SyncWithGroup(group) is a task. Each invocation stores group | 0x80 (the group’s low eight bits with the posted mark) as the actor’s posted value, then compares the channel’s released value with that stored byte. When they are equal it clears the mark, keeping the group, and completes; otherwise it keeps waiting. ResetGroupSync and the End operation set the actor’s posted value to zero.

Once per world-loop iteration, after the family system update, every channel is updated. The channel carries the mark when every non-excluded member’s posted value has its mark. The channel then releases a group: it scans cyclically over 0 through 127 for a value that some non-excluded member holds (its posted value without the mark; a member that has not posted holds zero, so zero counts), starting at the previous released byte itself. Because a marked released byte is at least 0x80, a marked release starts the scan just after its group, while an unmarked release starts at its own group. The first value found, combined with the mark, becomes the released byte; when none is found the released byte is just the mark. A member that completed keeps its group but loses its mark, so the channel advances to the next posted group unmarked until that member posts again or ends.

User synchronization channels

User channels have separate member lists and released bytes from group channels. Actors register in the channel named by data byte 30 at creation, with a posted value of zero. Lookups use the actor’s current byte 30; changing that byte does not register a new membership. World initialization clears both channel systems and enables them. World teardown disables them, frees their member lists and clears their released bytes.

SyncWithUser(value) completes immediately when synchronization is disabled, the current user channel is zero, or the actor has no member entry in that channel. Otherwise each invocation stores the low byte of value OR 0x80 in its member entry. It then stays pending if any member of that user channel has data byte 43 equal to zero. If every member has nonzero byte 43, it compares the channel’s released byte, zero extended, with the full operand value. Equality clears bit 7 of the caller’s posted value and completes; inequality stays pending.

The world-loop channel update processes each user channel immediately after its group channel. It builds a presence table indexed by each full posted byte of members whose data byte 43 is zero. Starting at the previous released byte, it checks up to 256 candidates. After each unsuccessful check the candidate becomes (candidate + 1) & 0x7f. The first present candidate becomes the released byte; if no candidate is present, the released byte becomes zero. It does not add a mark or require all members to have posted. In particular, the initial candidate can be above 127, while every subsequent candidate is at most 127.

ResetUserSync and End clear the caller’s posted user value to zero without changing the released byte or removing membership. They use the current byte 30 and do nothing when synchronization is disabled, that channel is zero, or the caller has no member entry there. ResetGroupSync uses the equivalent guards and current byte 29 for its group member entry.

PushAnimation and TaskStop: animation ownership

Each task slot saves and restores its native handler state independently. Multiple PushAnimation slots therefore retain separate not-started/started phases while requesting and observing the same receiving actor’s animation. Each invocation sees animation changes made by earlier calls; the animation is not copied into the task slot.

TaskStop clears matching operand slots and their blocking and pause flags. It does not invoke the native handler or restore earlier animation state. Stopping a PushAnimation task therefore leaves its animation request and current playback state in place.

PushControlAnimation(group, count) is a task with the same two phases as PushAnimation. Not started, it requests the group through the ordinary request unless the receiver’s current group already equals it; in that case it sets the loop count and becomes started. Both outcomes keep the task pending. Started, it completes when the current group no longer equals the group. Otherwise it turns the receiver and stays pending: the heading becomes the heading minus the scaled right turn amount plus the scaled left turn amount, modulo 2048, using the ground-turn accumulators and frame scale. The accumulators update every input update, whether or not the player controller runs.

Player alignment ownership and targets

PlayerLineUp(angle, x_offset, z_offset) moves the selected player relative to its receiving actor. Both distance modes move the player; neither moves the receiver. Its return value is also stored in the shared player-lineup result used by activation admission.

The first invocation in a native handler state selects the distance mode. It compares the shared integer three-axis distance between the effective player and receiver positions against SYSTEM.INI lineup_distance * 256. A strictly greater distance selects approach mode; equality selects close alignment. Subsequent invocations retain that choice in the native state. The initialized marker, mode, fallback flag and retained close-alignment reference belong to that handler state. Active task slots save and restore them independently. They are separate from the shared activation-admission result.

For the normal target calculation, add angle to the reference actor’s heading and wrap to 2048. Rotate the supplied horizontal offsets by that heading and add the reference actor’s local X/Z. The final player heading is the rotated heading plus 1024, wrapped to 2048. Approach mode uses the current receiver as reference. Close alignment retains its first reference in native state and uses that actor on later invocations. The target position is recalculated on each invocation; it is not a captured destination.

In the normal path, approach mode faces the destination before forward movement. Close alignment faces the final heading first, then chooses forward, sideways or backward movement from the relative destination bearing. Reaching the destination does not by itself finish alignment. The player must finish turning to the final heading and request its default animation. A completed alignment clears the player’s alignment flag and returns zero; ongoing alignment returns one. In approach mode, a retained fallback flag or a nonzero packed collision-response word masked by 0x01e2 switches to facing the receiver’s current local X/Z. Completion in that branch also sets the native return-state byte to 6. Close alignment’s fallback instead turns to the final heading derived from its retained reference, requests the default animation, and sets that byte to 6. Both completion branches clear the player’s alignment flag.

Approach mode’s movement step runs after the player has finished facing the destination and the movement-distance check permits movement. It is one call of the player’s WalkForward helper with duration 1, preceded by a saved copy of the player’s position, step counter and animation state. If the bearing from the new position to the destination, relative to the player’s heading, then lies from 256 through 1792 (the destination is no longer ahead), the step is undone, the player’s X/Z are set to the destination and the retained fallback flag is set. After the movement, a nonzero collision-response word masked by 0x01e2 together with a collision counter above 8 also sets the fallback flag. Approach mode returns one on every call that does not complete.

Close alignment’s movement step runs when the player has finished turning to the final heading and the movement-distance check permits movement. Let b be the player’s heading minus the heading of the displacement to the target (the heading the facing step turns to), wrapped to 2048 (the same quantity approach mode tests). The helper is chosen by b: right for 257 through 768, backward for 769 through 1280, left for 1281 through 1792, forward otherwise. Each helper first saves the player’s position, packed step counter, animation state and the two animation words that follow it, then calls its stepper with duration 1: MoveRight, MoveLeft, WalkForward or the walking backward step. It keeps the step when its test passes, otherwise it restores everything it saved, clears that direction’s shared called flag, sets the player’s X/Z to the target and reports failure, which sets the retained fallback flag. With b' the bearing measured again after the step, the keep tests are: right, b' from 257 through 767; left, b' from 1281 through 1791; forward, b' above 1792 or below 256; backward, the horizontal distance to the target no greater than before the step. After the step, a nonzero collision-response word masked by 0x01e2 also sets the fallback flag. Close alignment returns one on every call that does not complete.

PlayerPickupLineUp and PlayerParallelLineUp

PlayerPickupLineUp(angle, x_offset, z_offset) and PlayerParallelLineUp(angle, x_offset, z_offset) are tasks that move the selected player relative to the receiving actor; ObjectPickupLineUp and ObjectParallelLineUp run the same two movers on another actor. They do not store the shared player-lineup result. Each invocation first pushes a collision query frame for the player (position, a radius from the player’s model record scaled by a constant, or 200 when it has none, height word) and pops it afterwards. Unlike PlayerLineUp the offsets are added to the receiver’s local X/Z unrotated: the target is the receiver’s position plus the offsets (Y from the receiver), and the target heading is the receiver’s heading plus angle, wrapped to 2048.

The pickup mover returns zero when done and one while continuing. On its first invocation (elapsed time zero) a blocked straight path to the target (a segment of at most 0x20000 units, tested against objects but not the receiver or the player) selects the parallel mover for the rest of the task; the choice is retained in the task’s native state. Otherwise each invocation, in order:

1. A nonzero packed collision-response word with an age above 8 clears nothing but abandons the task: return state 6, return zero.
2. The player’s roll is leveled and the player faces the target; while still turning it returns one.
3. The facing arrival test snaps onto the target: all four called flags are cleared, the default animation is requested and the task returns zero.
4. When the movement-distance check permits movement, one forward close step toward the target runs (as in close alignment); a failed step also clears the called flags and completes as in 3.
5. Otherwise a stale collision response abandons the task as in 1, clearing the player’s alignment flag, and the task returns one.

The parallel mover works from the final heading angle + 1024 (wrapped): when the player’s heading is more than 768 from it the player turns to face angle + 2048, backs toward the target with a backward close step while the movement-distance check permits it, and completes once the backward step fails and the turn to the final heading has finished (called flags set); otherwise it turns to the final heading (returning one while turning), snaps on arrival (called flags set, default animation requested, return zero) and otherwise takes the close step that the relative bearing selects, as in close alignment, returning one unless the collision response is stale.

Alignment distance thresholds

Alignment position tests use local Q8 X/Z and the shared integer distance function with Y set to zero. They select a speed byte from the current animation group and actor attributes. Missing animation or attributes selects zero. Other groups also select zero.

Let speed be that byte and scale the Q8 frame scale. The alignment arrival test uses (((2 * speed - 1) << 8) * scale) >> 8. The facing helper’s arrival test instead uses (((speed + 1) << 8) * scale) >> 8. Products wrap to signed 32 bits and the final shifts are arithmetic. A horizontal distance less than or equal to the threshold snaps local X/Z to the target and registers a map update. Y remains unchanged. With speed zero and a positive ordinary scale, the first threshold is negative and cannot admit a nonnegative distance. The facing helper’s test can still snap in that case.

The movement-distance check is a third test. It uses ((speed * 512 - 1) * scale) >> 8, with the same wrapping and signed shift. It permits a movement attempt for actor state 7, speed zero, a nonpositive threshold, or a distance strictly greater than the threshold. It does not snap or register the actor.

Alignment turning uses the support-response turn rules, including selected-player camera updates. Returning to the default animation reports success on every normal return; it does not wait for playback to finish.

Player turn, speed, arctangent and location-distance queries

PlayerArctan() returns the arctangent angle (0 through 2047) of the horizontal displacement from the selected player to the receiver (or to the stored fallback position when no player is selected), the negation modulo 2048 of the bearing PlayerLooking uses.

PlayerTurned() returns 1 when any of the selected player’s three angles differs from the angles saved at the ordinary update’s entry, otherwise 0. PlayerTurnedDirection() returns the sign of the change of the player’s negated yaw ((2048 - yaw) & 2047) since the saved one: 1 when it grew, -1 when it shrank and 0 when unchanged, with the sign inverted when the change exceeds 1024. Both return 0 for an actor without a model handle.

PlayerMovementSpeed() returns an attribute byte of the selected player selected by its current animation group: groups 18 and 30 attribute 8, 19 attribute 9, 20 and 21 attribute 12, 22 and 23 attribute 13, 24 through 27 attribute 10. Other groups, and a player without animation state or attributes, return zero.

DistanceToLocation(location) returns the rounded Euclidean length, in Q8 units, from the receiver’s position (its linked position when it has one) to the location, selected as in MoveToLocation.

PlayerOnScape

PlayerOnScape() returns 1 when the selected player’s last ground-response record is a terrain contact and 0 otherwise. The ground update clears the record’s kind byte, sets it to 0x40 for a terrain contact and to 0x20 for a model or actor face, and retains the record for the selected player after its update.

PlayerStatus

PlayerStatus() classifies the selected player and returns the class of the first matching rule, or zero. The rules test, in order: the queued-motion byte (1 gives 1, 2 gives 2, 8 gives 3, 3 gives 4), the falling byte (2 gives 5, 8 gives 6, 3 gives 7), a nonzero sliding byte (8), the living-state byte (10 gives 9, 11 gives 10, 20 gives 11, 21 gives 12), the current animation group (18 or 30 gives 15, 19 or 23 gives 16, 24 or 25 gives 17, 26 or 27 gives 18, 20 or 21 gives 19, 22 gives 20), and last whether the player’s local position differs from its position saved at the update’s entry (21). Classes 13 and 14 repeat the living-state tests of 9 and 10 and are never returned.

BounceObject

BounceObject(power, speed, steer) is a task that launches its object (the selected player in installed content: BounceObject(160, 40, 1)) up and forward, then leaves the descent to the ordinary falling controller. It reports one while it runs and zero when done. The lifecycle byte moves through 30 (entry requested), 31 (rising) and 32 (falling). The first invocation refuses, ending the task with no effect, when the item system is not ready, the lifecycle byte is 30 or 31 or in 10 to 19, the surface is deep water (2 or 4), or power is zero. Otherwise it clears the falling, queued-motion and sliding bytes and the first two motion-vector words, sets lifecycle 30 and requests animation group 114 with a weapon held, 66 with a burning torch, otherwise 65.

Every invocation then runs, in order:

1. While the lifecycle byte is 30: if the current animation group is not 114, 66 or 65, clear the same motion bytes and words and report one. Otherwise set lifecycle 31 and set the lift to attribute 32 (jump height in map units) times 256.
2. If the object is the selected player and steer is nonzero, subtract the ground-turn delta (scaled right amount minus scaled left amount) from the heading, modulo 2048.
3. Move forward along the heading by ((128 - speed) << 8) / 3 (truncating division) times the frame scale, shifted right by 8, in Q8 units.
4. While the lifecycle byte is 31: subtract lift * scale >> 8 from Y and ((256 - power) << 4) * scale >> 8 from the lift. A lift above zero requests group 112 with a weapon held or the stance bit 0x04 set, 38 with a burning torch, otherwise 39, and clears the motion bytes and words as above. A lift of zero or less starts an ordinary fall (fall origin Y plus attribute 32 times 256, timer 30, falling byte 1), requests group 113 (forced) with a weapon held or the stance bit set unless the current group is already 115, otherwise group 57 with a burning torch or 56 (forced), and sets lifecycle 32. Either way the call reports one.
5. Otherwise, when the falling byte is zero set lifecycle 0 and report zero; else report one.

The lift shares the fall-origin word. “Weapon held” is the ordinary holding-weapon predicate.

The ordinary update’s ground response begins with a handler for the actor’s lifecycle states 27 through 32. For states 30 and 31 it reports the update handled, so the ground response does nothing (no support query result is applied, no fall starts). State 32 is not handled: the ordinary falling and landing response runs, and the falling byte it clears ends the task as above.

PlayerFaceObj

PlayerFaceObj is a task that turns the selected player to face its receiving actor. It reports one while the player is still turning and zero when done, and each invocation sets or clears the player’s alignment flag accordingly. The alignment flag is the hook-disabled bit that DisableHook sets, so the player’s native hook (its controller) does not run while the player is being aligned.

An invocation first checks the player’s packed collision-response word (the body-response byte, the transition byte and the two auxiliary bytes). When the word is nonzero and the collision-response age is above 8, it sets the native return-state byte to 6, clears the alignment flag and reports zero without turning.

Otherwise it applies the alignment roll leveling, then the facing step. Using the player’s alignment speed, a horizontal distance (Y zero, local Q8 X/Z) to the receiver at or below the facing arrival threshold snaps the player’s X/Z to the receiver’s, registers a map update and reports zero. Farther away, the target heading is the negated arctangent angle of the horizontal displacement from the player to the receiver (the heading the PlayerLooking bearing reports), wrapped to 2048, and the player turns to it by the support-response turn rules: zero when the heading already matches or the turn snaps to it, otherwise nonzero. A zero result clears the alignment flag and a nonzero one sets it, and the task reports that result.

GetAttribute, SetAttribute, GetMyAttr, and SetMyAttr

GetAttribute reads an unsigned byte from the receiving actor’s attribute table and returns zero when the table is absent. SetAttribute returns zero. When the table exists, it writes the low byte of the supplied value. Writing attribute 6 also copies that byte to attribute 115; writing attribute 1 also copies it to attribute 119. These two handlers do not check the attribute index range.

GetMyAttr reads an unsigned byte from the receiving actor’s attribute table. It returns zero when the table is absent or the index is outside 0–255. SetMyAttr returns zero and ignores an absent table or an out-of-range index. A valid write truncates the supplied value to its low byte. Attribute 44 also stores that truncated byte as the combat death-default group when the actor has a combat record and its object-update exclusion is nonzero. No other index has a write-time effect: attachment, rotation, family and model attributes are read where they are used, and a write neither rebinds the family nor refreshes the model.

Initial attribute copy and defaults

Loading an actor creates an independent 256-byte copy of its definition’s RAAT attributes, then applies these adjustments before registering its groups:

The effective jump settings come from [system] jump_time and jump_height in SYSTEM.INI. Values below 1 use 6 and 80 respectively. These load-time defaults do not run again on ordinary attribute writes.

Actors loaded through the animation model-table path also replace attribute 125, attr_mess_group, with the next value from a shared counter. The counter returns its current value, then increments modulo 256. Opening an actor-definition map resets this shared counter to zero before reading the map records. The counter is shared across actor definitions and instances, rather than restarting for each definition. The static-model shortcut and actors without models do not take this assignment path.

A type-1 MPOB placement has a subsequent model fallback. It runs only when actor-definition loading left both the animation model table and the static model absent, and the placement’s model name is nonempty. If the placement’s is_static byte is exactly one, it loads a static model without assigning a message group. Any other byte value builds an animation model table, using that byte as its frame count. When the actor has an attribute table, this fallback replaces attribute 125 with the next shared counter value. A zero frame count still takes the animation-table branch.

SetAttribute and SetMyAttr: default-group side effects

SetAttribute first writes the low byte to attribute 44. Only when IsDead returns true does it release the actor’s two held walk-node reservations and store the full supplied value as the combat death-default group. A node’s ownership byte is cleared only when it matches the low byte of the actor identifier; both actor-held node indices are then cleared. This operation does not reset the animation cursor, current group, or loop countdown.

SetMyAttr writes the combat death-default group only when a combat record exists and the object-update exclusion is nonzero. It stores the truncated attribute byte and does not release walk-node reservations. This exclusion check is distinct from the IsDead predicate used by SetAttribute.

The combat death-default group and the animation playback default are separate state. Ordinary actor updates select the playback default using actor state; these attribute writes do not directly replace that selection step. See ordinary default selection.

PlayerDistance and PlayerFacing

PlayerDistance() returns the sum of the absolute X, Y and Z differences between the selected player’s current position and the receiver’s effective position. Positions and the result use the runtime coordinate scale of 256 units per world unit. Without a selected player, it uses the global fallback position. A global override selects the fixed result 9999999 instead of calculating distance. The override is the nonzero neversaydie cheat state. Cheat initialization clears it before loading the optional REDGUARD.CHT file; without that file it starts disabled.

Fresh ordinary actor allocation starts without a linked-position record. This record is separate from the attribute-based master/slave attachment.

Effective receiver position follows the same selection used by positional sound: a nonzero attr_slave selects attached position; otherwise a valid linked positioned record supplies position, with the receiver’s ordinary position as the final fallback.

AcuratePlayerDistance() is PlayerDistance with the rounded Euclidean length of the same three-axis difference instead of the sum of absolute differences. It uses the same positions, the same fallback position without a selected player, and the same fixed 9999999 result under the neversaydie override. The length follows the node-marker distance arithmetic.

PlayerFacing(offset, tolerance) compares orientations. It adds offset to the receiver’s effective yaw, wraps the sum modulo 2048, and compares it with the selected player’s current yaw. The signed difference is wrapped into [-1024, 1024]; the result is one when its absolute value is less than or equal to the signed tolerance, otherwise zero. The offset and tolerance are full signed 32-bit arguments. The receiver’s attached yaw is used when attr_slave is nonzero; otherwise its ordinary yaw is used. This function requires a selected player. See coordinate and heading units.

PlayerLooking(tolerance) tests the selected player’s horizontal orientation relative to the receiver. Subtract the receiver’s effective X/Z position from the selected player’s ordinary X/Z position, retaining signed 32-bit differences. Convert that displacement to the quantized actor heading. This query retains signed 32-bit wrapping absolute values and signed comparisons during bearing reduction. The minimum signed coordinate difference therefore does not behave like a widened positive magnitude. Compare it with the selected player’s current yaw plus 1024, wrapped modulo 2048. The result is one when the absolute wrapped angular difference is less than or equal to the signed 32-bit tolerance, otherwise zero. A negative tolerance always rejects. The query requires a selected player and uses the same effective receiver position selection described above. It does not perform a visibility or line-of-sight query.

PrintSingleParm(value) formats the receiving script’s name (or Unknown script when the actor has none) and the signed integer as <name> <value> and writes the text to the first free of the console’s 66 text lines. It drops the text when no line is free and returns zero.

PlayerInSight() is true when the selected player is within 262144 units of the receiver and nothing blocks the line between them. The distance is the rounded Euclidean length of the difference between the two actors’ local positions, with no effective or attached position substitution; a longer distance is false and exactly 262144 passes. The segment between the two local positions, in whole map units, is then tested against each entry of the retained candidate model list, in order, exactly as the combat “In sight” test described under the combat decision rules does. An entry that is not hit, or whose owner is the selected player, does not block; any other hit makes the result false.

The candidate model list is one engine-wide list that every candidate gather replaces. A receiver that gathers no candidates of its own (an actor without collision) tests against the list the most recent gather by any actor left, which is empty before the first gather.

AtNodeMarker: node-marker distance

AtNodeMarker(marker, distance) returns one when the receiver’s ordinary local position is within the supplied distance of the indexed marker, otherwise zero. It uses all three axes and does not select attached or linked positions. Marker coordinates are converted from map units to runtime units by a left shift of eight bits; coordinate subtraction retains the low 32 bits.

The distance is Euclidean. Each signed difference is first stored as a single-precision float. The sum of squares passes through a double-precision store before an extended-precision square root; the root is stored at single precision and converted to a signed integer with nearest-even rounding. Rounding the root to double precision before the single-precision store can change the result at a single-precision midpoint. The result is compared with the signed distance argument using an inclusive bound. The distance argument therefore uses 256 units per map unit.

Marker lookup is fatal for an out-of-range or absent marker. While a world is loaded, the lookup reads that map’s own marker table: the index must be below the map’s marker count and the presence byte must equal one. A fixed 128-slot table that accepts any nonzero presence byte is read only when no loaded map is active. The marker argument is an unscaled signed index, distinct from the distance units.

Navigation map validation

Walk-map construction clears its runtime disabled byte, so newly loaded maps are enabled. This byte is separate from installed node reservation bytes.

Common actor initialization clears the current walk map and sets the held current-node, next-node and final-destination indices to -1. Later actor loading or navigation can assign a map and node; raw allocation zeroes do not describe these initialized navigation indices. The previous-next record starts at allocation zero; common initialization does not overwrite it.

Map placement loading supplies the authored local position before loading the actor. Actor loading then assigns its current node and map through the general nearest-node query, using each local coordinate shifted right by eight. This initial association does not add the actor’s Y extent and does not filter node reservations. It is separate from the combat nearest-free-node search.

An actor without a current walk map clears its current-node, next-node and final-destination indices to -1. An enabled map remains valid when each of those indices is below its node count; the -1 unset sentinel is allowed.

An index at or above the node count invalidates the map. Validation releases held current/next reservations, clears all three indices, and removes the map. A disabled map also releases held current/next reservations and removes the map, but retains the final-destination index until the next validation observes the absent map.

Reservation release clears a node’s ownership byte only when it matches the low byte of the actor’s runtime identifier. It clears the actor’s current and next indices even when another actor owns the node. An index at or above the node count does not address a node during release.

Current-node assignment releases the held next node before the held current node. When a next node was held, it first copies that index to the actor’s previous-next record. Next-node assignment instead releases current before next and leaves the previous-next record unchanged. Both operations clear the released indices even when another actor owns their nodes.

After releasing, assignment claims the requested node only when its ownership byte is zero or matches the low byte of the actor identifier. A successful claim writes that low byte and the corresponding current or next index, and returns one. A rejected claim returns zero with both held indices cleared. With no map, both held indices are cleared and assignment returns zero without changing the previous-next record. Neither assignment changes the final destination.

Validation and held-node release preserve the previous-next record, including when they invalidate or remove the map.

Nearest free walk node

Combat perception can search all loaded walk maps for a free node before navigation begins. This differs from the general node-selection query because only nodes with a zero reservation byte qualify. The search reads the actor’s query position, shifts each coordinate right by eight, and adds the actor’s positive Y extent to the shifted Y coordinate. Node X/Z are unsigned 16-bit coordinates and node Y is signed 16-bit.

Maps and nodes retain their loaded order. The search minimizes Manhattan distance with an initial exclusive bound of 4096. Equal distances retain the first candidate. An improving candidate below distance 12 returns immediately, even if a later node would be closer. The shared winning map is cleared before searching. A miss leaves it absent and returns node index -1.

Nearest node within one walk map

Point navigation can search its current walk map for the destination node. The search takes map-unit coordinates, ignores reservation bytes, and rejects an absent or disabled map. It minimizes Manhattan distance with an initial exclusive bound of 4096. Equal distances retain the first node, and an improving candidate below distance 12 returns immediately. The shared selected map is cleared first. A hit sets it to the supplied map; a miss leaves it absent and returns -1. This search does not select a different map.

Walk-route search and next-hop selection

Walk-map loading sizes the shared route queue and visited array to the largest loaded map’s node count plus eight. Search starts with the current node at depth one. An unset current node returns -1; an equal current and destination node returns that node before testing map availability. Other searches reject an absent or disabled map.

The forward search processes its queue in order and visits each node’s links in authored order. A link qualifies when its unsigned cost is at most 2048, its target passes node admission and has not been visited, and the expanded node’s reservation byte is either zero or equal to the requesting identifier. The reservation test belongs to the expanded node, not the linked destination. Qualifying targets are marked visited and queued with the parent’s depth plus one. Finding the destination starts backtracking immediately. Exhausting the queue or its capacity returns -1. Costs filter forward traversal; they are not accumulated as a shortest-path distance.

Backtracking does not retain the parent that discovered a node. For each node, it scans earlier queue entries in reverse order for depth one lower. It looks up the first authored link from each candidate to the current node. Zero cost is not a predecessor. Among nonzero links, the smallest low fourteen cost bits wins; equal costs retain the first reverse-scan candidate. Backtracking repeats until reaching the initial queue entry and returns the next node after it. Failure to find a predecessor returns -1. The forward admission filters are not reapplied during this predecessor scan. Duplicate links can therefore affect backtracking through their first authored cost even when another duplicate caused forward admission.

Each predecessor scan clears two shared link-result flags. An improving link sets the first flag when cost bit 14 is set and the second when bit 15 is set. These flags are not cleared by a later improving link within that same scan. The final scan’s flags accompany the selected next hop. A shared backtracking-inhibition word equal to one returns -1 and clears both flags before scanning. Other values allow backtracking.

When the shared player-proximity exclusion switch is zero, node admission returns true without reading the player. When enabled, a valid node in a present map is rejected only when its rounded three-dimensional distance is strictly below the shared signed threshold. Node X/Z are unsigned and node Y is signed. The player coordinates are the local actor position shifted right by eight. An absent map or an index outside its node range returns true without a distance calculation.

Point-navigation command state

The point-navigation wrapper copies four retained actor values into shared command scratch before the navigation core runs and copies them back afterwards: a 32-bit command value, a 16-bit command word, a phase byte and a counter byte. The copy-back occurs for either navigation-core return value. Alternating actors therefore retain each actor’s own four values rather than inheriting the last actor’s scratch contents.

After copying command state back, the wrapper measures rounded horizontal Q8 distance between the local position and the retained previous local position. It compares that distance with the frame scale shifted left by 13 with 32-bit wrapping, interpreted as signed and arithmetically shifted right by eight. A strictly greater distance restores all three local coordinates from the previous position. Equality retains the new position. This rollback does not undo command-state copy-back or change the navigation core’s return value.

Common actor initialization sets the command word to 0xFFFF. It leaves the 32-bit command value, phase and counter unchanged; fresh allocation clears those fields before common initialization. A separate shared 32-bit pause delay is outside these copies. Loading or saving an actor’s command values does not reset that delay.

Native task resumption separately loads command scratch from the actor’s six native task slots. Each slot retains four 32-bit values, including the pause delay and packed command word/phase/counter. Saving a task copies those values back to the same slot. The point-navigation actor fields and the native task continuation are therefore distinct retained owners of values used during the same command invocation.

Before evaluating native operands, a statement call clears all four retained scratch words. A direct function expression also clears all four. An object-targeted function expression clears the first two words and the packed word/phase/counter, while retaining the point command’s 32-bit value. This encoding distinction applies even when the explicit object target is Me. The direct native-hook dispatcher performs neither setup reset. A newly allocated task slot saves the scratch resulting from its first native invocation.

The six-slot resume pass visits slots in order. An empty or paused slot saves the current shared scratch into that slot without invoking its native call. An active slot loads its retained scratch before invoking the native call. A still-pending call saves the resulting scratch. A completed call clears its call pointer and blocking flags without saving the resulting scratch back to its slot. Its resulting shared scratch remains available to later slots and actors. Each invoked slot increments its unsigned 16-bit call count once. The pass sums the blocking flags of still-pending calls with byte wrapping.

The ordinary actor main stage performs native-hook and combat maintenance before its body/task processing. Task resumption can therefore replace command scratch for a later actor even when that later actor has no active task of its own. The direct native-call dispatcher does not clear the shared pause delay.

Point navigation validates the actor’s map and held-node indices before checking the pause delay. A nonzero unsigned 32-bit delay consumes the shared nominal tick count with saturation at zero and returns pending for that invocation, including when the subtraction reaches zero. Routing resumes on a later invocation. The delay is shared across actor invocations, so another actor can consume the remaining delay. This delay is distinct from the signed combat lost-sight timer.

Point-navigation completion stores the low byte of its result code in the shared navigation result byte and releases the actor’s held current and next walk-node reservations. The map and final destination remain retained. It changes lifecycle selector seven to zero, leaves other lifecycle selectors unchanged, assigns attribute 1 to 13, and returns zero. This completion helper leaves the actor’s four retained point-command fields and shared command words unchanged; the enclosing wrapper still performs its command copy-back.

Before ordinary point movement, the blocked-route counter increments with unsigned byte wrapping when the collision-response auxiliary byte has bit 7 set, a map is present, and a next node is held. A resulting counter greater than eight selects phase 24. Otherwise the counter resets to zero.

Before the blocked-route counter, a body-response mark of bit 2 (a contact with another actor) whose overlap contact identifier is not one, outside phase 27, draws one raw engine random value. Its low two bits select: 1, the held next node becomes the previous next node and phase 27 is selected; 2, the shared pause delay is set to 36 and the call returns pending; otherwise nothing changes.

Collision response marks are then read. When the collision-transition byte’s bit 0 is clear, any of auxiliary-byte bits 1 or 7, or body-response bits 1 or 3, releases the actor’s held walk nodes and selects phase zero, whatever phase the blocked-route counter selected. When the transition bit is set, the held nodes are released too; a collision-response age below 16 then restores the three local coordinates from the actor’s retained stable position, and an older response selects phase 24 unless the phase is already 24 or 25.

Phase 24 is the back-off after a blocked route. It releases the actor’s held walk nodes, then steps backward for one update with WalkBackward when attribute 93 is zero and with MoveBackward otherwise (both with a frame count of one, and WalkBackward is MoveBackward in deep water), selects phase 25 and stays pending. Phase 25 changes nothing until the actor’s current animation group equals its default group, then selects phase zero. Both phases stay pending (lifecycle selector seven, attribute 1 unchanged) and register the actor once for a deferred map update.

The shared player-exclusion switch starts disabled during player setup and nothing in the executable ever enables it, so walk-node admission and held-target admission never reject a node on its account. Point movement consults this switch before falling/queued-motion handling. It is the same switch used by walk-node admission; held-target admission has its own position quantization and angular checks.

A falling actor or one with queued motion assigns attribute 1 to 13, selects phase one when a next node is held or phase zero otherwise, sets lifecycle selector seven, and returns pending. This path precedes immediate arrival and default-animation admission.

A motion direction of 15 takes the same path after first calling a ledge update that acts only on the selected player (and only while its attribute 105 is not one); for every other actor that call changes nothing.

Phases 11 and 22 skip the immediate-arrival test. For other phases, a successful immediate-arrival test copies the destination’s local X and Z to the actor while preserving local Y, admits the default animation, and completes with result zero. Default-animation admission always succeeds. It requests the signed default group with modifier zero through the forced animation-request path only when SYSTEM.INI animation processing is enabled, animation state exists, the actor is not excluded from object updates, and its current group differs from its default group. It does not change the actor’s default group.

After immediate destination arrival is rejected and collision response is resolved, point phases 1 and 27 process the held next node. With no next node, they release held reservations, select phase zero and remain pending. On arrival at the held next node, default-animation admission runs before current-node assignment. The phase then becomes eight regardless of whether the claim succeeds. These pending paths set lifecycle selector seven and register the actor once for a deferred map update. Attribute 1 remains 12.

When the held next node has not been reached, phases 1 and 27 face that node. A nonzero facing result retains the phase. A zero result selects phase two. Only after that zero result, nonzero attribute 90 calls Rnd(attribute90). A zero random result selects phase nine and stores (draw & 127) + 16 in the point-command word using another shared random draw. Other outcomes preserve the command word. These paths retain held nodes and history, set lifecycle selector seven and register one deferred map update.

Phase nine updates the point-command word using nominal ticks. It sign-extends the 16-bit word to 32 bits, compares that value as unsigned with the tick count, and clears the word when it is smaller. Otherwise subtraction wraps into the 16-bit word. A zero result selects phase two. A held weapon also selects phase two, preserving the updated word.

An unarmed actor with a nonzero remaining word stays in phase nine. If its current animation group equals its retained default group, it consumes one shared draw. When the low five bits are all set, it draws again and masks to two bits, rejecting three until a value from zero through two is obtained. It requests animation group one plus that value with modifier zero. Other animation groups consume no idle draws. These paths retain navigation indices, set lifecycle selector seven and register the actor for a deferred map update.

Animation-stop calls in point navigation return without changing playback, actor motion or navigation state.

Held-node arrival validates the actor’s navigation and tests local horizontal Q8 distance against ((speed + 1) * 256 * frame_scale) >> 8. Equality is accepted; products wrap at 32 bits and the shift is signed. Speed is the current animation group’s movement speed without the immediate-destination fallback. On success, local X/Z snap to the node’s unsigned X/Z coordinates scaled by 256, local Y is preserved, and the actor is registered for a deferred map update. Registration deduplicates the actor, including when the enclosing pending path also registers it. A missing map reports held-node arrival before reading a node.

Phase two releases held nodes and selects phase zero when no next node is held. Otherwise it faces the next node when the animation exit marker is clear, ignoring that facing result, then invokes coordinate walking toward the node with tolerance zero. A pending walk retains phase two. A completed walk performs default-animation admission again and the held-node arrival test with tolerance zero. A failed arrival selects phase zero without releasing held indices. Successful arrival assigns the next node as current and selects phase eight even when the claim fails. These pending paths set lifecycle selector seven, leave attribute 1 at 12 and register one deferred map update.

Point direct visibility

Point direct visibility reads the receiver’s query position and compares the rounded three-dimensional Q8 distance to the destination with an inclusive limit of 131072. A larger distance rejects before model tests. The segment endpoints are each shifted right by eight to integer map coordinates.

The query visits the prepared mixed-model candidates in order. A type-16 candidate is skipped before geometry when its actor is the receiver or selected player, or its model is the receiver’s own model instance. Other candidate types do not receive that early exclusion. Model segment tests disable early return after subobject admission; that argument does not set polygon sidedness. Point direct visibility leaves the shared polygon-sidedness flag unchanged. Scene initialization enables that flag, and temporary bounds queries restore it to enabled before returning. A zero or failure result does not block. A successful model result blocks unless the candidate actor is the receiver; that receiver exception occurs after the geometry call. The first blocking result rejects immediately.

Point route initialization

Phase zero releases held nodes and admits the default animation before trying to initialize a new route. Initialization releases held nodes, performs the ordinary nearest-free-node search and copies the shared selected map into the receiver, including an absent map on a miss. A missing map or node returns zero. Otherwise it assigns the found node as next and returns one after the assignment; the assignment’s claim result does not change that return value.

A nonzero initialization result selects phase one. A zero result retains phase zero. The pending tail sets lifecycle seven and attribute 1 to 12 and registers a deferred map update. Ordered release and assignment preserve previous-next history.

Phase-eight route monitoring

An unset current node releases held nodes and selects phase zero. Otherwise phase eight searches the current map for the destination’s XYZ coordinates, each shifted right by eight. A missing destination completes point navigation with result byte two. When the destination equals the current node, held nodes are released. Nonzero attribute 95 selects phase 21. With attribute 95 zero, a failed direct-visibility check completes with result byte four; an admitted check selects phase 22.

For a different destination, route search receives the current node, destination node and low identifier byte, followed by attributes 92 and 91. A missing next hop completes with result byte three. A next-node claim uses the ordinary ordered release and reservation owner. A rejected claim completes with result byte seven. An accepted claim selects phase one when the shared first-link 0x4000 flag is zero, or phase 12 when it is nonzero.

The pending tail sets lifecycle selector seven, leaves attribute 1 at 12 and registers a deferred map update. Completion stores its result byte, releases held nodes, changes lifecycle seven to zero, sets attribute 1 to 13 and returns zero before pending registration. Completion retains the phase-eight command phase and previous-next history.

Direct-route phases 11, 21 and 22

Phases 11 and 22 bypass the point entry’s immediate destination-arrival test. Phase 21 admits the default animation and completes with result byte zero on its ordinary return.

Phase 22 releases held nodes first. Nonzero attribute 95 selects phase 21. Otherwise it faces the original destination’s X/Z coordinates. A completed turn selects phase 11; a pending turn retains phase 22. The pending tail sets lifecycle seven and registers movement, with attribute 1 remaining at 12.

Phase 11 also releases held nodes first. Nonzero attribute 95 selects phase 21. Otherwise a failed direct-visibility check selects phase zero. An admitted check writes attribute 1 to 13, then invokes coordinate walking toward the original destination with the caller’s tolerance. Nonzero sliding state selects phase zero before that call but does not skip walking. Completed walking completes the point call with result byte zero.

Pending direct walking faces the original destination when the animation exit marker is clear, ignoring the facing return, then registers a map update and rechecks direct visibility. A failed recheck selects phase zero. The common pending tail sets lifecycle seven and repeats deduplicating registration; attribute 1 remains 13 on this path. The initial visibility rejection and the attribute-95 transition retain attribute 1 at 12 instead.

Phase twelve (leap link)

Phase twelve is selected when the claimed first link carries the 0x4000 flag. An unset next node releases held nodes and selects phase zero. Otherwise the stage runs the coordinate arrival test at the next node’s X/Z with the caller’s tolerance. An arrival assigns that node as the current node through the ordinary claim and selects phase eight. Without arrival, facing the node (the face-node turn used by phase one) that returns zero starts the leap: the receiver is given queued motion 2 and its animation requests group 32, or 33 with a burning torch. The pending tail is the common one, with attribute 1 at 12. Its start is refused, leaving the phase unchanged, while the receiver is the selected player in its post-jump cooldown, its group is 114, 116, 130 or 131, its falling, queued or sliding byte is nonzero, its stored surface is 2 or 4, it is attached to a rope, or its living state is outside zero and 15. State 15 runs the hang release instead of starting the leap. A started leap clears the stable-position-valid flag, records the current Y as fall origin and zeroes the fall timer and sliding distance.

Coordinate walking and rollback

Coordinate walking saves local position, the packed movement byte and retained animation group/frame words before testing destination arrival. When arrival fails, it also saves the animation receiver. Attribute 93 equal to zero selects WalkForward; a nonzero value selects MoveForward, with duration one in both cases. The position-query owner is selected before movement and its coordinates are read after movement for destination bearing. That owner can supply alternate or linked coordinates rather than local position.

If the masked difference between bearing and local heading lies from 256 through 1792 inclusive, walking clears the shared forward-movement-called flag and restores the saved local position, movement byte, animation receiver and retained group/frame words, then snaps local X/Z to the destination. Local Y remains the saved Y. Otherwise it retains the movement result and returns one.

An initial arrival also snaps local X/Z and retains local Y. After either snap, default-animation admission runs and the coordinate walker returns zero. Default-animation admission returns one on every ordinary return, whether it issues a forced request or skips it. Its result remains one after a forced request. The empty animation-stop call changes no playback state.

Walk-node arrival distance

Node arrival compares horizontal distance from the actor’s local position to the destination, using the same rounded Euclidean distance as node markers. It accepts equality in:

distance - tolerance <= (((speed + 2) * 256 * frame_scale) >> 8)

Coordinates and tolerance use runtime Q8 units. Multiplication and subtraction wrap at 32 bits, and the final right shift is signed. Vertical distance does not participate. A missing navigation map reports arrival before reading a node.

Speed comes from the actor’s current animation group when it provides a nonzero movement speed. Otherwise it is the minimum nonzero attribute among indices 8, 19, 17, 12, 9, 13 and 10. When all seven are zero, the fallback speed is 8.

Wander: destination selection and movement limits

Wander(radius, tolerance) validates the actor’s current navigation-map state and sets attribute 94, attr_node_in_use, to one. With no current map, validation resets the held current-node, next-node and final-destination indices to -1.

Ordinary map loading copies the authored runtime position into the stored home position before actor setup and attachment transforms. Actor setup selects its initial navigation map and current node through the global nearest-node query.

When the final destination is unset, Wander clears the actor’s saved navigation scratch state and chooses a candidate around its stored home position. The positive radius is converted from runtime units to map units by shifting right eight bits. Home and effective current-position coordinates are converted by integer division by 256, truncating toward zero. Candidate X and Z each equal home + radius - Rnd(2 * radius); candidate Y is the home Y. It repeats both random draws while the rounded horizontal Euclidean distance from the effective current position is at most half the integer radius. Distance rounding follows the node-marker distance arithmetic.

The candidate then goes through the global walk-node selection query. An empty loaded map list leaves the final destination unset. It does not bypass candidate selection or its random draws, and the next invocation tries again.

Wander finishes by measuring horizontal displacement from the actor’s saved previous local position. Its limit in runtime coordinate units is (frame_scale << 13) >> 8, with a wrapping 32-bit left shift followed by a signed right shift. If the rounded displacement exceeds the limit, it restores all three previous local coordinates. Equality retains the current position. The function returns the measured displacement before any restoration.

MoveToLocation: authored locations

Ordinary actor setup creates location 0 from the saved original home position, then appends the actor header’s RALC entries relative to that home. These stored locations remain unchanged when the actor moves or becomes family-local. Negative selectors or selectors greater than the stored location count use the home position. A selector equal to the stored count falls immediately beyond the allocated entries; ordinary valid selectors run from zero through count minus one.

MoveToLocation(location, duration) compares the shared signed task elapsed value with the signed duration. When elapsed is strictly greater than duration, it assigns the stored target to all three local position coordinates, queues the actor’s map update, and returns zero. Equality still performs a movement step.

Otherwise its source is the attached effective position when attr_slave is nonzero, or the local position when that attribute is zero. It subtracts source from target with wrapping 32-bit arithmetic and normalizes the resulting vector to signed Q16 components. Normalization converts each component to single precision, sums the squared components with extended intermediates, stores the sum to double precision, and takes its square root. The divisor is that length multiplied by 1/65536 and stored to single precision. A zero divisor produces three zero components. Each other component is divided by the divisor, stored to single precision, and converted to an integer with nearest-even rounding.

It separately measures the rounded three-dimensional distance from source to target using the node-marker distance arithmetic. Movement distance is signed integer division of that distance by duration + 1 - elapsed, truncating toward zero. It then multiplies by frame_scale with wrapping 32-bit arithmetic and shifts arithmetically right by eight bits. Each displacement component is ((normalized_component >> 8) * movement_distance) >> 8, again with wrapping multiplication and signed shifts. Displacements are added to the actor’s local position with wrapping arithmetic. The operation queues a map update and returns one, including when all three displacements are zero.

WanderToLocation(location, duration) selects its target and source as MoveToLocation does and normalizes the direction the same way. Its first invocation in a task slot sets a retained speed to the signed integer division of the rounded source-to-target distance by duration, truncating toward zero; the slot keeps that speed and ignores the elapsed input afterwards. Each invocation computes the step as the speed times frame_scale shifted arithmetically right by eight. It queues the actor’s map update. When the distance, measured again before moving, is greater than the step, each displacement component is ((normalized_component >> 8) * step) >> 8, added to the local position, and the task returns one. Otherwise the local position is assigned the target and the task returns zero.

Actor families and attached transforms

attr_master and attr_slave are byte-sized group identities. A nonzero slave identity attaches an actor to the matching master group. An actor can be both a slave of one group and the master of another, forming a nested family.

Family initialization scans identities 1 through 255. For each identity it selects the first matching master without a slave identity from the actor traversal list. It collects attached child masters separately from attached actors without a master identity. Each collection prepends matching actors, so its traversal reverses their encounter order.

The initialization traversal visits allocated map-cell registry identities in increasing order, preserving each cell’s actor list, then appends the persistent actor list. Registry identities are assigned to cells as they are allocated; sorting cell coordinates does not define this traversal. Fresh actor allocations prepend to their cell or persistent list. Duplicate root masters are permitted: the first matching root is selected, and the other roots remain independent.

Initialization saves each master’s original position and angles before processing its descendants. Descendants are initialized before the child master’s own coordinates become local. For each attached actor:

1. Subtract the parent’s saved original position from the actor’s position.
2. Multiply that displacement by the transpose of the parent’s orientation matrix to obtain the local offset.
3. If the parent’s attr_no_slave_rot is zero, subtract the parent’s saved original angles from the actor’s angles, wrapping each component modulo 2048.
4. Initialize the attached-position storage with the resulting local offset.

The angle subtraction tests the parent’s attribute. The later composition branch tests the attached actor’s own attribute.

Family refresh

Each family refresh caches the root master’s current position and angles. It composes each child master before visiting that child’s descendants, then processes the remaining attached actors. Attached positions use the runtime coordinate scale of 256 units per world unit:

effective_position = parent_effective_position + parent_matrix * local_offset

Refresh preserves the previous attached position before storing the new one. Render position components use the effective integer coordinate shifted arithmetically right by eight bits, then converted to single precision.

When the attached actor’s attr_no_slave_rot is zero, refresh copies the parent matrix and applies negative local yaw, pitch and roll in that order. Its effective angle fields separately add the parent’s effective angles and local angles, wrapping each sum modulo 2048. A child master publishes its effective position and angles for descendants. Matrix composition and effective Euler angle addition are separate operations.

When the attached actor’s attr_no_slave_rot is nonzero, position still uses the parent matrix and translation. Its existing orientation matrix instead receives negative local yaw, pitch and roll changes relative to the saved previous local angles. Its effective angle fields use the local angles modulo 2048 without adding parent angles.

Ordinary axis locks

Near the end of an ordinary actor update, after script and movement handling, nonzero position-lock attributes 40, 41 and 42 restore X, Y and Z respectively from that update’s saved position. Rotation-lock attributes 38, 37 and 39 restore pitch, yaw and roll respectively from the saved angles. Each axis is independent, and the current attribute values are read when this step runs. Actors with nonzero attr_slave bypass all six restorations. The step restores coordinate and angle fields; it does not rebuild the orientation matrix.

Integer matrix arithmetic

Both local-offset initialization and position composition convert each signed integer input to single precision first. Matrix elements are single precision. Products and additions use x87 intermediates; each completed component is stored to single precision before conversion to an integer. Single-precision stores and integer conversion use the ordinary nearest-even rounding mode, as in the forward-probe transform. Parent translation is integer addition after conversion.

For row-major matrix entries m00 through m22, ordinary composition evaluates:

X = (y * m01 + x * m00) + z * m02
Y = (x * m10 + y * m11) + z * m12
Z = (x * m20 + y * m21) + z * m22

The transpose used during initialization evaluates:

X = (y * m10 + x * m00) + z * m20
Y = (x * m01 + y * m11) + z * m21
Z = (x * m02 + y * m12) + z * m22

Matrix axis updates

Axis rotations use the shared rotation table. For the supplied wrapped angle a, s is table entry a and c is entry a + 512. For each existing matrix row (x, y, z), the helpers write:

Both expressions use the row values from before that axis operation. The helper rounds the temporary result first, stores the other result in the matrix, then copies the temporary into the matrix. Each result is single precision before the next axis operation. Products and sums use x87 intermediates. Family composition applies these operations to the copied parent matrix with negative local yaw, negative local pitch and negative local roll, each wrapped modulo 2048.

Angle snapshots and script ordering

Explicit orientation assignment initializes the previous-angle fields from the assigned angles. The ordinary actor update copies current local angles into those fields before animation, movement and main script processing. Actors excluded from that update do not take this snapshot.

The ordinary family-composition branch reuses these fields for propagated angle deltas. Each component becomes (local_angle - saved_local_angle + parent_delta) & 2047 and supplies the delta for descendant processing. The attr_no_slave_rot branch leaves these fields unchanged and passes their stored values onward.

In the normal main loop, family refresh precedes map-list rendering and the ordinary actor update. A separate ground-settling path also invokes family refresh. A local-angle write does not itself refresh attached position, matrix or effective angles. Consequently, an ordinary script’s RotateByAxis followed by PlayerFacing reads the previously composed attached yaw until another family refresh occurs.

RotateByAxis: relative rotation

RotateByAxis(axis, delta, duration) modifies the receiver’s local angles. Axis zero selects X, axis one selects Y, and every other axis value selects Z. Angles wrap modulo 2048. A zero delta or zero duration completes without changing an angle.

The task keeps a target and accumulator with eight fractional bits. When the saved target and the task elapsed input are both zero, it initializes the target to ((current_angle + delta) & 2047) << 8 and the accumulator to current_angle << 8.

Each invocation computes a fixed-point step by shifting delta left eight bits, dividing by duration with signed truncation toward zero, multiplying by the current shared frame scale, then arithmetic-shifting right eight bits. The intermediate shifts and multiplication retain their low 32 bits. If this step is zero and the shared whole nominal-tick increment is nonzero, that tick increment becomes the step, negated only when the saved target is negative.

The task compares the absolute shortest wrapped angle difference between the current angle and target >> 8 with abs(step >> 8). If the difference is larger, it adds the step to the accumulator, writes (accumulator >> 8) & 2047, and remains active. Otherwise it writes target >> 8 and completes. The initial invocation can change the angle. Arguments are reevaluated on later invocations, while the saved target and accumulator persist unless the initialization condition is met again.

Each task slot owns its target and accumulator; the receiver’s angle is shared. Stopping the task removes its slot without restoring an earlier angle. Transform and attachment updates consume the changed local angles separately; the handler does not update their matrices itself. Frame scale and nominal ticks are distinct inputs; see animation timing.

sRotateByAxis: elapsed relative rotation

sRotateByAxis(axis, delta, duration) stores the selected angle as its origin whenever elapsed input is zero. Only axes zero through two select and write an angle. The origin remains task-local on later invocations.

For a nonnegative delta, the offset is ((delta << 8) / duration * elapsed) >> 8. For a negative delta, it computes that expression using the absolute delta, then negates the shifted result. Division truncates toward zero and the right shift is arithmetic. Intermediate shifts, multiplication and negation retain their low 32 bits. The handler writes (origin + offset) & 2047.

When elapsed is at least duration - 1, it overwrites that result with (origin + delta) & 2047 and completes. Otherwise it remains active. Thus the last invocation snaps to the full delta rather than the interpolated offset. Duration one completes on the initial invocation. Duration zero produces a division-by-zero fault before the completion check. This task uses elapsed input, not shared frame scale or nominal ticks, and does not refresh composed transforms.

RotateToAxis: absolute rotation

RotateToAxis(axis, target, duration) modifies the receiver’s local angle. Axis zero selects X, axis one selects Y, and every other value selects Z. The target is masked to 2047. A zero duration completes without changing an angle.

Let difference be the masked current angle minus the masked target. The signed movement toward the target is -(difference & 2047) when the difference is below -1024, -difference when it lies between -1024 and 1024 inclusive, and 2048 - difference when it exceeds 1024. Thus the two half-turn ties retain the direction determined by the subtraction.

Each task slot stores this movement with eight fractional bits and a separate angle accumulator. When the saved movement and elapsed input are both zero, it initializes them to movement << 8 and current_angle << 8. Later argument reevaluation changes the destination used for completion, but does not reinitialize a nonzero saved movement.

Each invocation divides the saved movement by the current duration with signed truncation toward zero, multiplies by shared frame scale, then arithmetic-shifts right eight bits. Shifts and multiplication retain their low 32 bits. If the result is zero and the whole nominal-tick increment is nonzero, the step is that increment shifted left eight bits, negated when the saved movement is negative.

The handler compares the absolute movement from the current angle to the current target with abs(step >> 8). If it is larger, the handler adds the step to its accumulator, writes (accumulator >> 8) & 2047, and remains active. Otherwise it writes the masked target and completes. The initial invocation can change the angle. The handler does not refresh the receiver’s composed transform or attachment matrix.

sRotateToAxis: elapsed absolute rotation

sRotateToAxis(axis, target, duration) stores the selected angle as its origin whenever the elapsed input is zero. Only axes zero through two select and write an angle. The origin remains task-local on later invocations.

It subtracts the stored origin from the target before masking the target. When this signed difference is below -1024, it replaces it with difference & 2047. When it exceeds 1024, it replaces it with -(difference & 1023). Other differences remain unchanged.

The interpolated angle is the origin plus ((difference << 8) / (duration - 1) * elapsed) >> 8, masked to 2047. Division truncates toward zero, the right shift is arithmetic, and intermediate arithmetic retains its low 32 bits. The interpolation executes before the completion check. A duration of one therefore produces a division-by-zero fault even at elapsed zero.

When elapsed is at least duration - 1, the handler overwrites the interpolated angle with target & 2047 and completes. Otherwise it remains active. The positive-difference mask can make the interpolated path approach a different angle before this final snap. This task uses elapsed input rather than shared frame scale or nominal ticks.

MoveObjectAxis: actor-local movement

MoveObjectAxis(axis, delta, duration) moves along the receiver’s orientation, using its current stored matrix or the upright forward shortcut. Delta and position use eight fractional bits. Zero delta or duration completes immediately. At elapsed zero, the task stores delta as its target and resets its traveled accumulator. Each invocation computes (delta / duration >> 8) * frame_scale with signed division, arithmetic shift and wrapping 32-bit multiplication, then adds that step to the wrapping accumulator. A negative step completes when the accumulator is at or below the target; a positive step completes when it is at or above the target. These completion paths perform no movement and do not snap the receiver to the target.

Otherwise, axis 0, 1 or 2 selects a local X, Y or Z displacement; other axes select a zero vector. For axis 2, a receiver with zero slave attribute, pitch and roll uses the upright forward translation rule, including single-precision coordinate addition and truncation. Other cases transform the displacement through the stored actor matrix, round the transformed components to nearest-even integers, and add them to the receiver’s coordinates with wrapping arithmetic.

After movement, the receiver is registered once in the deferred map-update list. The task remains active only while signed elapsed is less than the wrapping value duration - 1. Later invocations reevaluate arguments while retaining target and accumulator unless elapsed is zero again. The task does not perform collision or restore position when stopped.

MoveByAxis and sMoveByAxis: relative movement

MoveByAxis(axis, delta, duration) changes a receiver’s local position in the same eight-fractional-bit units as the position fields. Axis zero selects X, one selects Y, and every other value selects Z. A zero delta or zero duration completes without changing position.

Each task slot retains a target, initially zero. Whenever that saved target is zero, the handler replaces it with current_position + delta; this test does not depend on elapsed time. Each invocation divides delta by duration using signed truncation toward zero, arithmetic-shifts that quotient right eight, then multiplies by the shared frame scale, keeping the low 32 bits. This order quantizes the step before multiplication.

For a negative step, a proposed position at or below the target snaps to the target and completes. For a positive step, a proposed position at or above the target does the same. Otherwise the step is added to the current position. A zero step leaves position unchanged at this point. The handler then compares the signed task elapsed input against duration - 1: reaching that value snaps to the saved target and completes; otherwise the task remains active. Additions and subtraction wrap to 32 bits. The initial invocation can move the actor.

sMoveByAxis(axis, delta, duration) is a separate elapsed-position task. Only axes zero, one and two read or write a coordinate. Its saved origin starts at zero; when both origin and elapsed input are zero, it captures the selected current coordinate. Each invocation writes origin plus (((delta << 8) / duration) * elapsed) >> 8, using signed division, an arithmetic right shift and low-32-bit intermediate results. When signed elapsed is at least duration - 1, it instead writes origin + delta and completes. Other axis values still perform arithmetic and completion testing but do not write position. This handler has no zero-duration shortcut.

MoveAlongAxis(axis, delta, duration) is a task that moves along an axis of the receiver’s own orientation. A zero delta or zero duration completes without change. The slot retains the delta and a running sum, both reset when the signed elapsed input is zero. Each invocation computes the step as for MoveByAxis (signed delta / duration, arithmetic shift right eight, times the frame scale, low 32 bits) and adds it to the running sum. A negative step completes when the sum is at or below the delta, and a positive step when it is at or above it; that invocation does not move the actor. Otherwise the step becomes a vector on the selected axis (zero X, one Y, any other value Z), is rotated and added to the local position, and the actor registers a map update. With attribute 36 nonzero, or while the receiver’s per-update matrix-use byte is zero (it is cleared at the start of every ordinary update), the rotation is built from the receiver’s current pitch, yaw and roll; that sense is the inverse of the stored matrix’s transform, so a quarter turn of heading sends a positive X step onto negative Z. Only with attribute 36 zero and the matrix-use byte set does the stored matrix rotate the vector in the stored matrix’s own sense. The task then completes when duration - 1 is not greater than the elapsed input. It never snaps to a target position.

Both tasks reevaluate their arguments on subsequent invocations and retain slot state under their respective initialization conditions. Neither handler performs collision, matrix, or attachment refresh. Stopping a task does not restore position. Signed division overflow, including division by zero in sMoveByAxis, has no successful movement result.

Rnd and QuickRnd

Rnd(bound) and QuickRnd(mask) each consume one draw from the shared engine random stream, also used by sky scroll initialization. The generator updates an unsigned 32-bit state with wrapping arithmetic:

state = state * 1103515245 + 12345
draw = (state >> 16) & 32767

The executable’s stored initial state is 1. The state belongs to the shared generator, not to an individual script or actor.

QuickRnd(mask) returns draw & mask, using the complete 32-bit argument. The argument is a bit mask rather than an exclusive upper bound. A zero mask still consumes a draw; a negative mask is accepted.

For a positive bound, Rnd(bound) first masks the draw with the smallest mask in 1, 3, 7, ..., 16383 whose range can contain bound values. Bounds greater than 16384 leave the draw unchanged. It then repeatedly subtracts the bound until the result is less than the bound. Equivalently, apply that mask and take the remainder modulo the bound. The result is not uniformly distributed for every bound. Zero and negative bounds do not define a valid bounded draw.

HideMe and ShowMe

HideMe() sets the receiver’s hidden flag and clears its current presentation record. ShowMe() clears that flag. For a static-model receiver, showing it also restores its model presentation record and refreshes its transformed geometry. Both calls return zero.

The hidden flag does not exclude the receiver from ordinary script or animation updates. It suppresses the ordinary actor’s optional sound and light updates. Player selection also uses this flag to hide the unselected player model.

Current model presentation

A retained model resource and an actor’s current model presentation record are distinct. For an actor admitted to the ordinary presentation traversal, the current record is cleared before hidden and update-excluded state are checked. Either exclusion therefore leaves that actor without a current model record. The PVO actor predicate runs earlier: an actor rejected there retains its prior current record as well as its stored coordinates. Stored floating-point model coordinates have a separate lifetime. Actor default initialization clears them to zero. Clearing the current record, hidden or update exclusion, and PVO rejection preserve those coordinates until model-position processing runs again. An absent animation frame or unavailable selected resource also preserves the previous coordinates when position processing is skipped. A static-model actor that passes those checks restores its retained resource and refreshes its model position and orientation, even when the retained resource is null. Drawing exclusion suppresses submission without clearing the restored record.

For an animation-table actor, an unavailable selected model or an absent frame selection clears both the selected resource and the current presentation record. Collision candidate construction consumes the current record and its stored model transform. A logical position change does not itself refresh that transform. In normal main-loop order, model presentation runs before the ordinary actor update. ShowMe() provides the separate immediate static-model refresh described above.

The ordinary model-position path uses the actor’s logical Y shifted right by eight when the collision attribute mask 0x04 is clear. With that mask set, water processing can adjust model Y for stored surface classes 1 through 5 and 11. Other stored surface classes retain the shifted logical Y. A nonzero collision attribute by itself therefore does not establish water displacement.

The normal world loop enables water-position processing before its frame loop and clears that enable when it leaves the loop. A nonzero attribute 26 bypasses this model-position path before water processing; family refresh owns the attached actor’s model coordinates.

For other actors, a linked-position record with a nonzero owner reference selects a separate model-position calculation before water processing. Copy the record’s local offset, convert its components to single precision, and transform it by the owner’s stored orientation matrix. Each resulting component is converted to an integer using the active floating-point rounding mode. The default mode rounds to nearest, with ties to even.

Select the owner’s effective position, add the transformed offset and the actor’s own local logical position, then shift each signed component arithmetically right by eight and store it as a float. Both integer additions wrap at 32 bits before the shift. The actor’s logical position is unchanged. This linked calculation returns before water displacement, health prepasses or environmental effects. A missing linked record or zero owner reference instead falls through to ordinary model positioning. The linked record’s cached position used by effective-position queries is a separate value from this calculated model position.

For the selected player with attribute 105 equal to one, enabled water-position processing and collision attribute mask 0x04 run an earlier surface prepass. Stored surface classes 2 and 4 clear both directional-state words before a health change of -255 through the selected death-owning health service, with no source actor. Classes 1 and 3 clear those words without that health call. Other surface classes do neither in this prepass. The later surface-position processing still follows; this prepass does not replace the surface-5 and surface-11 route.

With water-position processing enabled and collision attribute mask 0x04 set, stored surface classes 5 and 11 place the model Y at the arithmetic-shifted logical Y plus 64. For the selected player, the retained death-progress word is also added. These integer additions wrap at 32 bits before conversion to the floating-point model position; the logical position is unchanged.

Stored surface class 1 places model Y at the arithmetic-shifted logical Y plus 64. Surface classes 2, 3 and 4 first check the selected player’s retained hit inhibition. An inhibited selected player uses shifted logical Y plus 64 plus retained death progress, then returns without coverage sampling or the height-change effect check.

Otherwise, surface 2 uses coverage 256. Surfaces 3 and 4 sample terrain material blend coverage at the stored model X and Z, each truncated toward zero to integer map units. Coverage zero and 256 remain unchanged. Other coverage values are doubled and capped at 256. Model Y becomes shifted logical Y plus one quarter of that coverage, using an arithmetic right shift by two.

Animation groups 141 through 143 then add [game] swim_depth to the stored model Y. This setting replaces zero with 40 during initialization; other values are retained. The shifted-position result is stored as a float before the swim-depth addition, whose result is also stored as a float. Group 140 does not receive that offset.

For the non-inhibited surface-2/3/4 path, the prior stored model Y is truncated toward zero. The new stored Y is subtracted, and the difference is truncated toward zero before taking its integer absolute value. A magnitude strictly greater than 16 requests environmental effect descriptor 0x2500; equality does not. Surface 1 and the inhibited selected-player path skip this check.

This environmental effect starts from the actor’s current logical Q8 position. Its horizontal point is displaced 2048 Q8 units toward the camera using the camera-relative effect-point rules. Its vertical point is logical Y plus the actor’s positive vertical extent times 256 plus 1536, with signed 32-bit wrapping arithmetic. The effect constructor applies texture-height centering and publishes map-unit coordinates, descriptor flags, the texture’s last frame as the target frame, and speed one. This path consumes no random numbers. Disabled effects or refused allocation produce no effect.

The selected player’s surface-5 path sets retained death mode one after publishing model Y. Surface 11 leaves that mode unchanged. Both paths then test queued motion and the low two bits of each directional-state byte. A nonzero queued-motion state or either nonzero bit pair suppresses the health call; it does not undo the model position or death-mode write. Otherwise the receiver gets a health change of -255 through the death-owning health route. The selected player’s mode write therefore precedes any death initialization performed by that health service.

Model admission and support ownership

Both standalone player roles are allocated into the persistent actor list. The initially selected player is allocated first and the alternate second; insertion at the front leaves the alternate before the selected player in that list. Model-list assembly appends this persistent list after the collected cell actors, so standalone players participate without an MPOB placement. Player setup hides the alternate. It remains linked but hidden-state exclusion prevents its model position processing.

The current map’s PVO file supplies a camera-centered selected-object list. An empty selected list leaves ordinary model admission unrestricted. With a nonempty list, the ordinary presentation traversal excludes actors with attr_non_moving set. This predicate also applies to standalone players.

With a nonempty selected list, animation-model admission also reads the actor’s retained support owner. A static-placement support must occur in the selected MPSO IDs. Support from an actor with attr_non_moving set must occur in the selected secondary object IDs. Other support cases pass this admission check. Rejected animation-model admission still runs model-position processing when a frame is selected, then clears the selected resource and current model record. An absent frame skips position processing. Thus rejected support can still produce model-position health changes and environmental effects without publishing geometry.

When loading a world with a PVO file, the secondary object table is built from the complete map actor traversal. Map cells are scanned in increasing Z, then increasing X, preserving each cell’s actor list. The persistent actor list follows the cells. Only actors with attr_non_moving set are appended to the secondary table, in that traversal order. This cell-coordinate scan is distinct from the registry-identity traversal used for family initialization.

Ordinary actor updates clear the retained actor and static-placement support owners before ground processing. A selected model face assigns its candidate’s actor and static-placement owners. Model presentation precedes that ordinary update, so its admission reads support retained from earlier ground processing. Actor-following also consumes the retained actor support owner.

Global Flags

369 global flags (indices 0–368), shared across all scripts. Each flag has a declared type:

The loader maps BOOL, FLIPFLOP, COUNTER, and NUMBER to runtime kinds zero through three. Initializing a flag stores its authored numeric value and clears the latch. A BOOL set toggles its numeric value only when unlatched, then latches it. FLIPFLOP toggles on every set. COUNTER decrements a nonzero value and latches it; a zero value remains unchanged. NUMBER sets the latch without changing the numeric value. The SOUP SetGlobalFlag and ResetGlobalFlag wrappers return zero. TestGlobalFlag returns one or zero according to the latch.

Native flag functions maintain a separate latch in addition to the numeric flag value. TestGlobalFlag reads that latch; ResetGlobalFlag clears it. SetGlobalFlag dispatches according to the runtime type bits and can toggle, decrement, or latch a flag. It is not a generic assignment of one to the numeric flag.

Flags are declared in the [flags] section of SOUP386.DEF and accessed by bytecode via SetGlobalFlag, TestGlobalFlag, and ResetGlobalFlag (which use the NumericAlt opcode 0x16 for their flag-ID parameter).

Six flags have non-zero defaults: TimeOfDay (1), OB_TelV (1), OB_TelH (12), At_Shoals (1), Rock_1_Down (1), Rock_2_Down (1).

Flag categories span narrative progression (acts 1–8, for example After_Catacombs, After_League, Won_Game), inventory state (HaveAmulet, HaveGem, Equipped_Torch), NPC dialogue tracking (DreekiusTalk, TobiasTalk, SionaFriend), puzzle mechanics for catacombs (CTDoor*, CTWeight), caverns (CV_Lock*, CV_Pillar*), observatory (OB_TelV, OB_Platform), palace (PI_Door*, PI_Throne*), dwarven ruins (DR_Steam, DR_Boiler, DR_Pipe*), and the scarab (SCB_Position, SCB_ArmL, SCB_ArmR), as well as runtime control (Talking, MenuRet, StrengthTimer, MapTimer).

Relationship to RGM Sections

• RAHD stores per-actor script pointers, variable counts, and function-table indices.
• RASC stores compiled script bytecode as a contiguous blob.
• RAST/RASB store script string literal data and offset tables.
• RAVA stores initial local variable values (i32 array).
• RAHK stores per-actor native call records addressed by RAHD section offsets.
• RAAT stores per-actor attribute tables (256 bytes each), addressed by names from SOUP386.DEF.

See RGM.md for record-level layouts and offsets.

External References

• UESP Mod:RGM File Format
• RGUnity/redguard-unity RGRGMScriptStore.cs — SOUP VM interpreter with dispatch loop, threading model, and formula evaluator
• RGUnity/redguard-unity soupdeffcn_nimpl.cs — SOUP function ID-to-name table (367 functions)
• Dillonn241/redguard-mod-manager ScriptReader.java — RASC bytecode disassembler with full opcode and value-mode decoding
• Dillonn241/redguard-mod-manager ScriptParser.java — RASC bytecode assembler (script text to bytecode)
• Dillonn241/redguard-mod-manager MapHeader.java — RAHD record parser with field offsets
• Dillonn241/redguard-mod-manager MapDatabase.java — SOUP386.DEF parser (function, flag, reference, attribute definitions)

Selected-player location camera task

showCyrusLoc is a three-argument task. It tests IsHoldingWeapon on the selected player, independently of the receiving actor. While that predicate is true, the task returns zero without invoking its camera-location handler.

Otherwise it passes the selected player and all three full-width arguments to the camera-location handler and returns that handler’s result. The wrapper does not narrow or transform the arguments. Task-slot scheduling and operand reevaluation follow the ordinary native-task rules.

Player camera task state

showPlayer is a task with no arguments. Each invocation asks the player camera selector for a slot, falling back to slot zero when the selector reports no selection. It updates the shared camera selection to that slot.

The task increments its first private word with 32-bit wrapping. When the result is one and elapsed input is zero, it sets bit 0x01 in the selected camera record’s flags and returns one. Otherwise it clears bits 0x01 and 0x20 in that record and returns zero. Other bits in the record’s flag byte are retained. The private word belongs to the task continuation and is distinct from the shared camera selection.

A nonzero task result keeps the task slot active and zero completes it. The initial invocation therefore leaves showPlayer active with bit 0x01 set, and the next task pass completes it after clearing bits 0x01 and 0x20.

Player camera slot selection

The slot requested for the selected player is the first that applies:

When none applies, no slot is requested.

A request for a different camera slot changes the selection only when the shared transition word is zero or the current record has flag 0x01. Otherwise the current slot remains selected. Requesting the current slot leaves selection unchanged. The pose stage clears this word according to its correction and movement-limiting results.

Actor camera offsets

Location-camera setup reads the actor’s attr_camera_target_offset_x, attr_camera_target_offset_y, attr_camera_target_offset_z, attr_camera_offset_x, attr_camera_offset_y, and attr_camera_offset_z attributes as unsigned bytes. Each byte independently becomes zero when it is zero, or (value - 127) * 500 otherwise. The signed results replace the selected camera record’s target-offset and camera-offset vectors. This conversion does not change the actor attributes or the other fields in the camera record.

Selected record and selected index

The engine keeps the selected camera record and a separate selected-index word. Camera record selection sets both. The movement limiter’s slot-one test, the orientation stage and the distance-height stage read the index word; every other stage reads the selected record. A pan leaves the index on the slot being panned while the selected record is record two.

showPlayerPan

showPlayerPan(duration) is a task with one argument. It increments the same private word as showPlayer. A negative duration writes a diagnostic line and the task returns zero before touching the private word or any camera state.

On the first invocation (private word one, elapsed zero) it:

1. takes the slot the player camera selector requests, or zero, and makes that record the selected record directly, without the selection guard;
2. begins a scripted camera;
3. copies the requested slot’s record into record two and sets the selected index to the slot (the selected record stays whichever record the begin step left selected);
4. binds the selected record to the selected player;
5. records the camera’s current offset from the player, published position - record position offset - bound position, as the start vector. The start distance is that vector’s rounded length shifted right eight. The start angles are the camera orientation conversion of the vector. The target is the record’s angle offset minus the bound angles (not wrapped), and the delta is the target minus the start angles with each component wrapped once into half a turn either side of zero (below -1024 add 2048; above 1024 subtract 2048).

Every invocation then runs the scripted-camera release step with duration. While it reports running and duration is greater than one, the selected record’s flags 0x04 and 0x08 are cleared and, with span = duration - 1:

• each angle offset component is the bound angle plus the start angle plus delta * elapsed / span;
• the distance is the start distance plus (record distance - start distance) * elapsed / span;

products wrap as signed 32-bit values and division truncates toward zero. The task returns one.

Otherwise (the release step finished, or duration is one or less) the selected record receives the target as its angle offset and its own distance, flags 0x01 and 0x20 are cleared, the showPlayer step runs (it increments the private word again, selects the requested slot through the selection guard and clears flags 0x21 on it) and the task returns zero. Only record two is edited, so the slot’s own record is unchanged afterwards.

Location camera request

The first invocation of the location-camera handler (private word one, elapsed zero) sets flag 0x01 on the record that is selected at that moment, begins a scripted camera (see below), binds the record that step selected (record two) to the target actor, applies the actor camera offsets to it, and then writes its request from the three task arguments. The flag set on the first record stays set: after the handler, record zero (when it was the selected record) keeps flag 0x01.

The binding selects one of two position and angle vector pairs on the actor, chosen by attribute byte 26 (zero or nonzero). The camera therefore orbits the target actor, not the player.

The arguments are shifted left eight bits. That vector and the record’s position offset (as just replaced from the actor attributes) are each rotated by the bound actor’s angles. Flag 0x01 is set on the bound record again, and the actor’s attr_camera_move byte then selects:

Other values write no request and leave the flags as the begin step set them. The handler then runs one camera pose update with the bound record selected, clears flag 0x01 on the selected record, and returns one. Later invocations run the scripted-camera release step with argument zero and return zero.

showObj is the same handler with the argument vector used as given instead of rotated by the bound actor’s angles (only the record’s position offset is rotated); its requests are therefore vector + rotated offset + bound position (attr_camera_move 0), vector + rotated offset (1) and the orbit of the unrotated vector (2). The showCyrus wrappers of both handlers return zero without touching the camera while the selected player is holding a weapon, and otherwise run the handler with the selected player as the target actor.

Object pans

showObjPan and showObjPanLoc take a target actor, three vector arguments and a duration, and move the camera from where it is towards a request over duration ticks. The vector arguments are shifted left eight bits. A negative duration writes a diagnostic line and the task returns zero before touching the private word or any camera state. Both share the first invocation’s setup with the location camera: begin a scripted camera, bind the selected record (record two) to the target actor, apply the actor camera offsets, and rotate the record’s position offset by the bound actor’s angles. They differ in two ways:

The first invocation (private word one, elapsed zero) records the start state: the published camera position minus the bound position, as the start position; that position minus the rotated offset, whose rounded length shifted right eight is the start distance and whose camera orientation conversion is the start angles; the vector’s rounded length shifted right eight as the final distance; and the delta from the start angles to the vector’s angles, each component wrapped once into half a turn either side of zero. No flag 0x01 is set and no pose update runs; the normal camera update publishes the result.

Every invocation runs the scripted-camera release step with duration. While it reports running and duration is greater than one, with span = duration - 1, the actor’s attr_camera_pan_type selects the interpolation:

• one: the selected record’s request is the start position plus (vector + rotated offset - start position) * elapsed / span per component, with flag 0x04 set and 0x08 cleared;
• any other value: flags 0x04 and 0x08 are cleared, each angle offset component is the bound angle plus the start angle plus delta * elapsed / span, and the distance is the start distance plus (final distance - start distance) * elapsed / span.

Products wrap as signed 32-bit values and division truncates toward zero. The task returns one.

Otherwise the request attr_camera_move selects is written exactly as the location camera writes it (with the absolute request of the table above, the relative request being vector + rotated offset, and the orbit using the vector alone), flag 0x01 is cleared on the selected record, and the task returns zero.

The showCyrusPan and showCyrusPanLoc wrappers apply the same holding-weapon guard as the location wrappers and then run the handler with the selected player as the target actor.

World-position camera requests

showObjWorld(x, y, z) is a location camera whose arguments are a world position. Its vector is (argument - P) << 8 per component, where P is the position offset of the record that is selected when the task starts (the arguments are not shifted before the subtraction). The first invocation sets flags 0x20 and 0x01 on that record, begins a scripted camera, binds record two to the target actor, applies the actor camera offsets, sets flag 0x01 again and writes the request attr_camera_move selects. Nothing is rotated and the offsets are not added:

It then runs one camera pose update, clears flag 0x01 on the selected record and returns one; later invocations run the release step with argument zero and return zero.

showObjWorldPan(x, y, z, duration) returns zero for a negative duration without touching the camera. Otherwise it runs showObjPan with the arguments (argument << 8) - B per component, where B is the bound position of the record selected at the call, and showObjPan shifts them left eight bits again.

showObjRot does nothing and returns zero.

lookObj

lookObj(duration) turns the camera in place to face the target actor. A negative duration writes a diagnostic line and the task returns zero before touching the private word or any camera state.

The first invocation (private word one, elapsed zero) begins a scripted camera, binds the selected record (record two) to the target actor and applies the actor camera offsets. It keeps the published camera angles as the start angles and runs the camera’s orientation stage at the published position, with the record’s target offset, to get the angles that face the target; the delta is the difference from the start angles with each component wrapped once into half a turn either side of zero. It then sets flags 0x08 and 0x02 (fixed orientation) on the record, writes the published position as the record’s request, and returns one. The release step does not run on this invocation.

Every later invocation runs the scripted-camera release step with duration. While it reports running and duration is greater than one, the published camera angles are written directly: start angle plus delta * elapsed / (duration - 1) per component (products wrap as signed 32-bit values, division truncates toward zero), and the task returns one. Otherwise flag 0x02 is cleared and the actor’s attr_camera_move selects the request, using the published position P, the bound position B and the record’s position offset O:

Other values write no request. The task then returns zero.

Scripted camera begin and release

Beginning a scripted camera sets the scripted-camera active word to one, requests slot two (the selection guard applies), clears the first twelve bytes of the selected record twice, increments the nesting count, resets the record’s flags to 0x40 and sets flag 0x20.

The release step takes a duration argument. It selects slot two’s record, raising a shared reselection mark when the selected record changed. While duration - 1 exceeds the task’s elapsed input it returns one. Otherwise it decrements the nesting count, clears the active word when the count reaches zero, and returns zero.

Camera marks and the render camera step

Besides the published (logical) pose the camera keeps a render pose: three floats holding the position in whole map units and three angles. Four marks decide each frame whether the render pose glides towards the published pose or cuts to it.

Camera setup clears hold and forced glide and cuts the render pose to the first published pose (position shifted right eight bits, truncating toward zero; the angles unchanged). lookObj and showObjRot set no mark.

The render step runs once per frame after the pose update. First it clamps the render position’s x and z floats into [0, 65535]. Then it glides when the following chain reports a glide, the snap mark is clear and the frame mark is set:

1. hold set: cut;
2. forced glide set: glide;
3. the selected player holds a weapon, or is associated with a rope: glide;
4. the scripted-camera active word is nonzero: cut;
5. snap clear: glide;
6. the selected record has flag 0x20: cut;
7. selected index zero, three or four: glide; otherwise cut.

A glide uses the installed [camera] factors glide_x, glide_y, glide_z (0.9, 0.2, 0.9) and glide_angle_x, glide_angle_y, glide_angle_z (0.7, 0.1, 0.7). With p the published position shifted right eight bits as a single float and r the render position float, each axis becomes r + (p - r) * factor evaluated in extended precision and stored as a single. The result times 256, truncated toward zero, goes through the camera terrain correction, is divided by 256 truncating toward zero, and becomes the new render float. Each published angle is replaced by (previous + trunc((published - previous) * factor)) & 2047, where previous is the render angle, the difference is wrapped once into half a turn either side of zero, the single-precision product is truncated toward zero, and the factor for the first (pitch) angle is glide_angle_y and for the second (yaw) angle glide_angle_x; the third uses glide_angle_z. The published angles are therefore smoothed in place.

A cut sets the render position to the published position shifted right eight bits (truncating toward zero) and clears snap and hold. Every pass clears forced glide, and the final published angles become the render angles for the next frame.

Follow camera observation

The debug overlay’s World (x, y, z)-(pitch, yaw, roll) line is the published camera pose and its Player (x, y, z)-(pitch, yaw, roll) line the selected player’s, in whole map units and 2048-unit angles. With the installed defaults (record zero position offset (0, -14000, 0), distance 250, target offset (-6000, -14000, 0)), a player at (32464, -275, 33892) with angles (0, 22, 0) gave the camera (32481, -330, 33642) with angles (0, 2027, 0): the camera sits 250 units behind the player along the player’s heading, 55 units above, and looks at the player’s height. The angle triple’s orientation matrix carries local +Z along the look direction with the X axis mirrored.

Frame view angles and screen shake

After the render step the frame builds its view orientation from the published angles. A roll tilt would be selected by a mode word that nothing writes (zero), so no tilt is applied. A screen-shake level (0 to 32) wobbles the first angle: on even frames of the main loop’s frame counter the level is subtracted from the angle and then halved, on odd frames it is added and kept; each angle is then wrapped to 2047. One shake impulse raises the level by 32, capped at 32. Impulses come from the actor-event service (operand bit 0x10) and a debug key.

Ordinary camera selection inhibition

On the ordinary camera-update path, a nonzero scripted-camera active word or bit 0x20 in the selected camera record suppresses automatic slot reselection. The camera still runs its pose-processing stage. These guards precede the holding-weapon and other player-state checks used to choose an automatic slot; they do not suspend the whole camera update.

When neither guard applies, the ordinary camera-update path requests the slot from the player camera slot selection table and falls back to slot zero when no condition applies, so a player that sheathes its weapon returns to slot zero on the next update.

Camera request candidate position

The camera’s initial position-composition stage gives record flag 0x04 priority over 0x08. With 0x04, it adds the stored request vector to the record’s bound actor-position vector, with wrapping signed 32-bit components. Otherwise, with 0x08, it copies the stored request vector directly. These are candidate positions supplied to subsequent camera processing, not final rendered camera poses.

Before testing either request flag, this stage compares the stored distance shifted left by eight against the stored minimum, using signed comparison. If it is lower, the minimum replaces the distance without a compensating shift. Equality leaves the distance unchanged.

Without either explicit request flag, the stage rotates the record’s position offset by the bound angles. It separately constructs a vector with zero X and Y and negative distance shifted left by eight as Z. The angles for this second rotation are the bound angles minus the record’s angle offsets, masked to one revolution. Flag 0x80 replaces the first of these angles with the negated first angle offset, ignoring that bound-angle component. The candidate is the bound position plus both rotated vectors, with wrapping signed components.

Camera vector rotation builds an identity matrix, applies negative yaw, then positive pitch and roll, and transforms the supplied integer vector. These angle signs differ from the ordinary actor-matrix update convention.

Camera collision candidate radius

SYSTEM.INI [camera] obstacle_size supplies the candidate-size cutoff. Setup stores it with eight fractional bits, and collection shifts it back before comparing with each candidate model’s radius. The model radius must be strictly greater than this cutoff. This is separate from the added bounds-test radius computed from the queried segment.

Candidate collection subtracts the fixed-point endpoints before arithmetic-shifting the displacement components right by eight. It separately shifts the starting point by eight. Each shifted component is squared with a wrapping signed 32-bit multiply, made non-negative with a wrapping absolute value (the most negative value stays negative), and the three results are summed with 32-bit wrap. The added model-bound radius is twice the floor of the integer square root of that sum read as an unsigned 32-bit value, so a displacement long enough to wrap still yields a radius. The center-distance test accepts equality with the squared sum of the model radius and this added radius.

The bounds test stores each integer-origin minus model-center component at single precision, then stores their summed squared distance at single precision. It also stores the model radius plus added radius at single precision before squaring that combined radius for comparison. Equality admits the model.

Camera collision candidate eligibility

Candidate collection scans two linked object lists in order and appends model references to one candidate array. A model equal to the caller’s excluded model is skipped in both lists.

Entries of the first list carry a model and a bounds record. An entry is a candidate when its model and bounds are present, the bounds radius is strictly greater than the obstacle cutoff, and the segment bounds test accepts the model.

Entries of the second list are actors. An actor is a candidate when it has a model bounds record, is not excluded from ordinary object updates, and then passes the same model, radius and bounds tests. The bounds-record flag is set when the actor’s script and model load establishes its bounds; the exclusion is the flag the ordinary object-update loop tests.

The candidate array holds 64 entries. When it already holds 64, the engine writes a diagnostic line instead of appending and stops scanning the current list; the remaining entries of that list are dropped.

Camera collision result selection

The query arithmetic-shifts each fixed-point endpoint component right by eight before the geometry test. The integer wrapper converts returned hit positions with the active x87 integer rounding mode and scales normal components by 256 before converting them. Selected output positions are shifted left by eight; selected output normals retain the wrapper’s scale.

Polygon hits store their position along the tested segment as a rank: the segment parameter multiplied by 32768, converted with the active x87 integer rounding mode. The segment start has rank zero and the end has rank 32768.

The camera collision query counts all returned hit records independently of whether a record replaces either selected output. For segment ranks from zero through 32768, minimum selection starts at 32767 and requires a strictly lower rank. Maximum selection starts at zero and requires a strictly higher rank. Equal ranks retain the first selected record.

A result containing only ranks 32767 or 32768 therefore reports hits without replacing the shared minimum-position output. A result containing only rank zero leaves the shared maximum-position output unchanged. The query does not clear these output positions before scanning its candidates.

Camera collision response

The pose collision stage runs when the selected camera record has flag 0x40 and the shared collision-inhibition word is zero. It rotates the record’s target offset using its bound angles, adds the bound position, and queries the segment from that target to the candidate camera position. Candidate collection excludes the bound actor’s model instance.

A nonzero query hit count replaces the candidate camera position with the shared minimum-position output and reports success. A zero hit count leaves the candidate unchanged. The response does not separately check whether the query replaced its minimum output. An endpoint-only hit can therefore copy the retained minimum position from before the query.

Camera movement limiting

Camera record flag 0x01 bypasses the movement-limiting stage. Otherwise the stage uses both the last published camera position and the preceding position. Its scalar timing helper floors the signed frame scale at 180, multiplies with 32-bit wrapping, and arithmetic-shifts the product right by eight.

The movement budget starts with the distance between those two retained positions plus the shared budget increment, capped by the record’s unsigned maximum. The timing helper scales that budget. When the candidate displacement exceeds it, the stage forms an integer fraction with eight fractional bits and scales displacement components with multiplication followed by an arithmetic right shift. It reports that limiting occurred even when integer quantization leaves a component unchanged.

A separate vertical limit precedes this distance test except for camera slot one and the selected-player special-state branch. The lower bound is the timed vertical parameter. A displacement above its negation is replaced with the negation of the unscaled parameter. The two sides therefore do not use the same timing conversion. The selected-player special-state branch also retains the candidate’s horizontal components during distance limiting while still applying the vertical component and reporting limiting.

The shared budget increment is SYSTEM.INI [camera] max_acc. The vertical parameter is [camera] max_y_vel negated before storage, so it is the negative lower bound described above. Both are stored without scaling. Setup stores them with the other shared camera values, and the same values are reloaded when the selected player’s camera defaults are reloaded.

Camera orientation retention

Camera record flag 0x02 makes the orientation stage copy the previously published camera angles into the new pose. This branch skips target-direction calculation, leaves the record’s bound-position history unchanged, and does not refresh the two transformed camera vectors.

Without this flag, slots zero and one use only the target offset’s vertical component; other slots use the full vector. The stage rotates that offset by the bound angles, adds the bound actor position, and derives the camera angles from the direction between the published camera position and that target. It also refreshes the bound-position history and transforms both stored camera vectors using the derived angles.

Before angle conversion, the direction components are stored as single-precision values. Their Euclidean length divided by 65536 is stored at single precision. Each component is divided by that stored divisor, stored at single precision again, and converted to an integer with the active x87 rounding mode. A zero divisor produces a zero vector. Angle lookup consumes this quantized direction.

The direction is camera position minus the rotated target position. Using the signed bearing lookup whose positive X axis is a quarter turn and positive Z axis is zero, yaw is the X/Z bearing minus half a turn. Pitch is the bearing of the rounded horizontal length against Y, minus a quarter turn. Both wrap to 2048 units per revolution; roll is zero.

The two retained basis vectors use a direct angle matrix with positive pitch, negative yaw and positive roll. Each output component is a dot product with a matrix column. Vector inputs and dot products are stored at single precision; final integer components use the active x87 rounding mode.

Camera contact-normal response

The camera body-response stage converts the candidate fixed-point position to floating coordinates and gathers contact normals. It sums normal components after dividing their integer representation by 256. A nonzero sum is normalized. If the sum cancels to zero, it instead uses the first contact normal divided by 256, without normalizing that fallback.

The response truncates the camera body’s floating radius to an integer, multiplies it by the selected response direction, scales the result by 256, truncates each component toward zero, and adds it to the candidate position. No contacts leave the candidate unchanged. Opposing contacts can therefore produce a response in the first contact’s direction rather than no response.

Each accumulated normal component is stored at single precision after each addition. Normalization stores the reciprocal length at single precision, then stores each scaled direction component at single precision. Each product of the integer radius and selected direction is also stored at single precision before scaling by 256 and truncating toward zero.

Camera distance-height correction

Only slots zero and three run the distance-height correction. It subtracts the bound actor position from the candidate, divides each signed fixed-point delta by 256 with truncation toward zero, and computes the resulting distance. A zero distance is replaced with 0.1 for the following comparison and division.

When that distance is strictly below the record’s distance threshold, the stage scales the vertical delta by threshold divided by distance. It replaces candidate Y with bound actor Y minus the absolute scaled vertical delta converted back to fixed point with truncation toward zero. Candidate X and Z remain unchanged. Equality with the threshold leaves the candidate unchanged.

The divided deltas, summed squared distance, square root and threshold are stored as single-precision values. The vertical division and subsequent threshold multiplication each store a single-precision result before conversion back to fixed point.

Camera terrain-height clamp

When the terrain-height stage is enabled, both terrain queries receive candidate X and Z arithmetic-shifted right by eight. The floating height result is truncated toward zero before conversion back to fixed point. The camera body’s stored clearance parameter is multiplied by 1024 and truncated separately.

Only a candidate Y plus clearance strictly greater than the converted terrain height triggers correction. The replacement Y is terrain height minus clearance; X and Z remain unchanged, and the shared correction flag is set. Equality does not set the flag or replace the pose.

The terrain query converts horizontal coordinates to cells with the active x87 integer rounding mode after applying x / 256 - 0.5 and z / 256 + 0.5. When both cell offsets from the retained terrain-window center are strictly between -16 and 16, height comes from that retained grid. At either boundary or outside the window, it comes from map samples through the height lookup table. The camera query therefore does not always use the static map heights.

Each selected cell uses a triangle plane rather than bilinear interpolation. Its diagonal joins (i, j) to (i + 1, j - 1). When the horizontal offset x - i * 256 is greater than j * 256 - z, the third corner is (i + 1, j); otherwise it is (i, j - 1). Equality uses the latter triangle. The query publishes a normalized plane normal; the integer wrapper scales that normal by 256 and converts it using the active x87 integer rounding mode.

For plane construction, the first vertex is (i, j). In the greater-offset branch the next vertices are (i + 1, j - 1) and (i + 1, j); otherwise they are (i, j - 1) and (i + 1, j - 1). The two edges are second minus first and third minus second. Each edge component is stored at single precision before their cross product is formed. Replacing these adjacent edges with mathematically equivalent edges can change the sampled height through rounding.

Camera pose stage order

The pose stage composes a candidate and performs a segment collision check. A hit replaces the candidate with the retained minimum hit position, then runs distance-height correction, contact-normal response and terrain correction.

A second segment check follows on both paths. A hit again replaces the candidate with the retained minimum position. The stage then runs distance-height correction, contact-normal response, movement limiting and terrain correction, in that order, before publishing the pose.

Camera pose publication

The transition word clears when the pose stage reports a collision or terrain correction. Without such a correction, it clears only when its value is one and movement limiting did not occur. A limited update can retain value one; other nonzero values also remain unchanged without correction.

After position correction, the pose stage moves the previously published camera position and angles into their respective history vectors. It then publishes the new position to shared camera state and to both the camera actor and alternate camera actor. Camera setup stores the CAMERA instance as both, so the two writes address the same actor. Orientation processing follows position publication, and its result replaces the shared published angles.

Position history therefore contains the preceding published pose, not the new request or a temporary collision candidate. Retaining orientation still advances angle history to the preceding published angles.

Camera record initialization

Camera setup clears all nine records, initializes record zero, and copies that record into slots one through eight before applying slot-specific configuration. The copied fields include the selected-player binding, position and angle bindings, position offsets, angle offsets, distance limits and maximum movement rate. Record zero has collision flag 0x40 before these copies.

The ordinary target-offset configuration is assigned to record zero after the copies. It therefore does not initialize the other records’ target offsets. Combat target offsets are assigned separately to slot three. The remaining slots retain their cleared target-offset vectors at this initialization stage.

Camera initial state

Camera setup selects record zero. The shared transition word, the scripted-camera active word and its nesting count are zero. Setup then computes the first published pose with one pass of the pose stage that omits movement limiting, and stores it as both the current and the previous pose.

Camera update

The CAMERA actor’s script body ends immediately. Its native hook, cameraController, takes no arguments and is the camera update itself: the pose update for the selected record’s bound actor that the location camera natives also run. The hook runs once per ordinary update, at the camera actor’s position in the ordinary actor traversal.

ResetRotation

ResetRotation(x, y, z) acts on the receiver and returns zero. The actor keeps a triple of the pitch, yaw and roll it was created with (the angles it has when it is allocated; the player swap copies it between player records and XResetCamera sets it to the current angles). For each argument that is nonzero, the receiver’s pitch (x), yaw (y) or roll (z) is replaced by that retained component.

The previous-angle history then becomes the receiver’s current angles, and its orientation matrix is rebuilt. When the receiver’s rotation mode (attribute 28) is one, an alternate construction builds the matrix. Otherwise the matrix starts as the identity and takes rotations of the negated yaw, then pitch, then roll.

ReloadRotation

ReloadRotation() takes no arguments, acts on the receiver and returns zero. It performs the second half of ResetRotation without restoring any angle: the orientation matrix is rebuilt from the receiver’s current angles (by the rotation mode’s construction, as above) and the previous-angle history becomes the current angles.

ResetPosition

ResetPosition(x, y, z) acts on the receiver and returns zero. The actor keeps the world position it was created at. For each argument that is nonzero, the receiver’s local position on that axis (x, y, z) is replaced by the retained component, even for an attached actor. The previous-position history then becomes the receiver’s current local position.

When the receiver is the selected player, the shared view origin moves by the change the reset made on each axis. The receiver’s transform is then rebuilt.

MovePlayerAboveMe

MovePlayerAboveMe(x, y, z, angle) returns zero and asks for the selected player to be placed relative to the receiver. The offset (x, y, z) is rotated by the receiver’s orientation matrix and added to the receiver’s position (the world position of an attached actor, otherwise its local position, taken through the parent when it has one). The requested player Y is that sum minus the selected player’s positive Y extent shifted left eight bits, minus the [system] standing_height value from SYSTEM.INI shifted left eight bits; X and Z are the sum itself. The call stores this position and angle as one pending placement; a later call in the same frame replaces it.

The main loop applies the pending placement once per frame and then clears it. The selected player’s local position and its previous-position history both take the requested position, its yaw becomes angle & 0x7ff, and the camera is marked to cut instead of glide. The call has no other effect on the receiver.

XResetCamera

XResetCamera takes no arguments, acts on no receiver state and returns zero. In order, it:

1. Runs the LockoutPlayer routine for the selected player with zero.
2. Runs the KillMyTasks operation on the selected player and clears five flag bits (0x01, 0x02, 0x04, 0x08, 0x10) of the actor byte that immediately precedes its task arrays.
3. Rebuilds the selected player’s orientation matrix from its current angles and stores those angles in both of its retained angle-history triples.
4. Sets the scripted-camera active word and its nesting count to zero.
5. Applies step 2 to the camera actor.
6. Reloads record zero’s player-type defaults, selects record zero, resets its flags to 0x40 and recomputes the first published pose as setup does.

Camera record installed settings

Camera setup reads SYSTEM.INI [camera] integers and stores them without scaling except where stated. Record zero receives, before the copy to slots one through eight:

Record zero also gains flag 0x40. target_offset_x, target_offset_y and target_offset_z are assigned to record zero after the copy, and to slot three from the same keys.

Slot-specific settings follow the copy. Each replaces the slot’s angle offset and distance; a nonzero *_max_vel replaces its maximum movement rate, and a zero value keeps the copied record-zero rate.

The debug slot’s three angle-offset reads all store to the first angle-offset field; its second and third angle offsets keep the copied record-zero values.

Slot three gains flag 0x40 (already present from the copy). Slots six and seven additionally load aim vectors from camera_rope_above_aim_x/y/z and camera_rope_below_aim_x/y/z, bind the record’s aim reference to them, and set their flags to exactly 0x40. Slots four and eight keep the copied flags. Slot five gains flag 0x80 in addition to 0x40, giving 0xc0. Slots one, two and four through eight keep their cleared target-offset vectors.

obstacle_size and fudge_factor are shifted left eight bits and max_y_vel is negated before storage in shared camera state, outside the records.

SheathSword

SheathSword takes no arguments and returns zero. It acts only when all of these hold for the receiver: the task system is enabled, the receiver has animation state and a combat record, the combat cooldown is zero, the lifecycle byte is not in 27 through 32, the receiver is neither drawing nor sheathing a sword (the IsDrawingSword and IsSheathingSword predicates), and IsHoldingWeapon is true. Otherwise it changes nothing.

When it acts, the lifecycle byte becomes 21 (sheathing), the companion motion byte is cleared, bit 0x04 of the combat flags is cleared, and the combat cooldown becomes 24. For the selected player it additionally sets the HUD health-display timer to 25 and selects camera slot zero.

endCombat

endCombat takes no arguments and returns zero. It first does what SheathSword does for the receiver, including its eligibility tests. It then unconditionally sets the lifecycle selector (MyAIType) to 1 and the AI mode (MyAIMode) to 0, re-enables the receiver’s native hook as EnableHook does, clears combat flag 0x04, and zeroes the combat record’s close-distance pass counter and coordination selection state. A receiver without a combat record faults in the original.

FacePlayer

FacePlayer(duration) is a task that turns the receiver’s local Y angle toward the selected player. Each invocation computes the bearing from the receiver’s local position to the selected player’s local position as the arctangent angle of the displacement, which is the negation (modulo 2048) of the bearing the PlayerLooking query reports, then:

1. gap = (-heading - angle) & 2047, which is the PlayerLooking bearing minus the heading. A zero gap completes the task without a change.
2. remaining = |elapsed - duration|, treated as 1 when zero.
3. If gap is above 1024, gap = (-gap - 1024) & 1023 and the step is subtracted from the heading; otherwise the step is added.
4. step = ((gap << 8) / remaining) >> 8. A zero step completes the task without a change.
5. The heading wraps modulo 2048.

After a turn the task completes when elapsed >= duration - 1, and remains active otherwise.

FacePlayerInertia

FacePlayerInertia(duration) follows FacePlayer except for the step. After the gap is reduced as FacePlayer does (a gap above 1024 becomes (-gap - 1024) & 1023 and subtracts), the step is (((gap << 8) / duration) - elapsed) >> 8 with signed division and an arithmetic shift; a duration of zero is a division fault. A zero step, including a negative one that shifts to zero, completes the task without a change. The turn, the wrap and the completion test are the same.

Potion counters and combat strength and armor

SetPotion(index, value) stores the full 32-bit value in a global counter table and returns one. GetPotion(index) returns the stored value. The table is zero-filled when the engine starts and is not cleared by world changes. The shipped scripts use indices 0 through 3 (blood, milk, ectoplasm and sap items).

setStrength(value) and setArmor(value) store the full 32-bit value in the strength and armor fields of the receiver’s combat record and return nothing. They apply to a receiver that has a combat record.

Nonplayer combat decision: target, distance and engagement

The nonplayer decision stage (death and state selector 6, actor not dead) begins as follows.

The decision entry caches the current 32-bit clock sample for combat pacing and timed taunts. In normal clock mode this is the raw BIOS-clock sample, interpreted as signed. It is distinct from nominal-tick increments and from the world-loop frame counter. The world-loop counter resets to zero on loop entry and increments once at the beginning of each iteration. In the waiting branch, after spacing, one random draw admits a chance taunt when draw * 100 / 32767 < 2. The taunt type is 5 when the wrapping sum of the receiver’s allocation index and world-loop counter is even, and 8 when odd. Timed selection of that requested type still uses the cached clock sample. The active branch ends the same way: after spacing, counter-attack selection and defence selection, one random draw admits a chance taunt under the same draw * 100 / 32767 < 2 test, and the requested type is always 5.

Valid target. An actor is a valid combat target when it exists, it is not both in lifecycle state 8 and killed, it has a combat record, and its own combat target is not itself.

Target selection. When the receiver’s combat target is not valid, the target becomes the selected player, whether or not the player is itself a valid target, and the target’s local position is copied into the receiver’s retained target position. A valid target leaves that position unchanged until engagement succeeds.

Distance and counter. The distance from the receiver to its target uses the query positions of both actors (attached, linked or local, as for the fighting query) and the three-dimensional rounded distance. While that distance is below 25000 a counter in the combat record increments once per pass with signed 32-bit wrapping; otherwise the counter is zero. Combat construction and reinitialization clear this counter and the retained target position. After engagement succeeds, the target’s local position replaces the retained target position before the defence and attack executors run, in that order, each with request -1. An active result from either executor ends this decision pass before spacing and further selections.

Engagement. The receiver is engaged when attr_combat_ignore_in_sight is nonzero. Otherwise, with attr_combat_long_sight nonzero, it is engaged when the target is in sight within a distance of 0x80000; with it zero, within 0x40000. Both distances use the position’s eight fractional bits.

In sight. The test is false for an absent actor or target and when their distance exceeds the limit. Otherwise the segment between the two query positions, in whole map units, is tested against each entry of the engine’s retained candidate model list, in order. The test does not collect candidates itself: it reads the list collected for the receiver by ordinary actor traversal immediately before the receiver’s update (see Candidate collection for an ordinary update), so only models near the receiver can block the line. An entry that is not hit, or whose owner is the target, does not block; any other hit makes the result false. The result is true when no entry blocks.

Nonplayer defence selection

The defence selection runs only while the receiver is armed and the selected-player hit-inhibition flag is clear. Standalone-player initialization clears this flag; selected-player health death sets it. With no move selected, the target must lie inside the receiver’s forward arc and its distance must be strictly below the receiver’s far window. The forward-arc query subtracts the receiver’s local position from the target’s local position with signed 32-bit wrapping arithmetic, then arithmetic-shifts each coordinate right by eight. It obtains the normalized vector’s orientation and compares the receiver’s local yaw with (1024 - vector_yaw) & 2047. The absolute wrapped difference must be strictly below 256 heading units. Composed query poses are not substituted for these local positions. The defence counter becomes one when the headings differ by less than 256 heading units or the target is outside combat stance. Otherwise it becomes 129 - attribute 58. A target is in combat stance when it is armed or its combat flag mask 0x04 is set. The flag query returns false without a combat record; the action query returns -1. Heading differences mask both headings to 0 through 2047 and wrap the difference into -1024 through 1024.

The pacing sum is the receiver’s per-actor combat value plus the shared tick counter, with signed 32-bit wrapping addition. When its signed remainder by the defence pacing divisor is zero:

• For a target move other than -1 or 9, the target’s signed animation command cursor must exceed the wrapping sum of its current motion’s first_collide_frame and collide_duration. The current attack slot and motion selector choose that motion. This uses neither the displayed model frame nor the wrapping frame-progress byte. The receiver gains intent mask 0x01, then asks the best-usable-defence picker for a kind. A successful pick starts only if its reach test succeeds.
• For target move 9, the open-defence picker supplies a kind, which starts only if the pick and reach test succeed. This branch does not set the intent mask.
• For target move -1, neither of these picks runs.

After this branch, independently of its pacing remainder, a zero signed remainder of the pacing sum by the defence counter sets intent mask 0x01, obtains the paced pick and starts it if the reach test succeeds. Starts happen synchronously, before any later picker reads the combat state.

With a move already selected, the selection uses only the defence counter remainder. On zero remainder, defence selector zero requests kind one and selector one requests kind two; either request first sets intent mask 0x01. Other selectors do nothing. Intent updates preserve every other combat flag bit.

Best and open defence picks

Both pickers scan the receiver’s nine authored attack slots in ascending slot order. These are the attack slots bound from attributes 70 through 78, not the separate four defence records. The first motion supplies each slot’s distance window, near timing and counter-attack reference. Absent slots are skipped. A slot is usable only when the signed actor-to-target distance is strictly greater than its minimum range and strictly less than its maximum range. The best picker chooses the usable slot with the lowest signed near timing value, strictly below 65536. Equal values retain the earlier slot.

The open picker applies the same rules, but excludes a slot whose one-based counter-attack reference minus one equals the receiver’s current move’s counter-attack index. The subtraction wraps as signed 32-bit arithmetic. Best selection does not read counter-attack references. Open selection reads the candidate counter-attack reference, then queries the current move’s counter-attack index, only after that slot passes its distance window. An excluded slot does not read near timing. Each admitted slot repeats the current-move query. Both pickers map a winning slot of six, seven or eight to defence kind four. If no slot qualifies, they report failure without changing the caller’s output.

The current-move counter-attack query returns zero when the receiver has no combat record or its action selector is -1 or 9. These cases do not read attack or motion metadata. Otherwise, it resolves the receiver’s retained attack-slot selector and current motion selector, reads that motion’s authored one-based counter-attack reference and subtracts one with signed 32-bit wrapping. The action selector gates the query but is not the attack-table index.

Paced defence pick

The initial choice is zero. One random draw in the inclusive range zero through 32767 produces draw * 6 / 32767, with unsigned integer division. That slot replaces the initial choice only if it exists and passes the strict distance window. The maximum draw therefore probes slot six. This fallback does not require arc or elevation admission and does not remap the slot.

The picker then scans slots zero through five in ascending order. A populated slot must pass distance, arc and elevation admission, in that order. A failed test prevents the later tests for that slot. The fallback reads only existence and the distance window. Neither path reads the counter-attack reference. If the receiver and target face alike, or the target is outside combat stance, a slot replaces the choice only when its signed accumulated damage exceeds the retained damage, initially zero, and the pacing sum has zero signed remainder by the defence pacing divisor. A successful replacement retains that damage. Equal damage totals retain the previous choice.

Otherwise, each admitted slot resets the defence counter to 129 - attribute 58 before reading its near timing. This branch does not read accumulated damage. The picker tracks the lowest near timing strictly below 65536, with the same zero-remainder gate, but this branch does not replace the chosen slot. The final return is the fallback or the last priority-branch replacement. No qualifying slot leaves the initial choice of zero intact.

Defence elevation and arc admission

Both tests read the first motion of the receiver’s selected attack slot. Elevation admission uses the receiver and target’s bounds-query positions. For each coordinate, that query computes the signed 32-bit wrapping expression position - (negative_extent << 8) + (positive_extent << 8), then divides by two with truncation toward zero. It does not substitute the actor origin.

Let d be target bounds-query y minus receiver bounds-query y, with signed 32-bit wrapping subtraction. Let w be the wrapping sum of the receiver’s positive and negative x extents, each shifted left eight bits, and let h be w / 2, truncating toward zero. The required elevation is:

• One when -h > d and -(w + h) < d.
• Otherwise two when d > h and w + h > d.
• Otherwise zero.

All additions and negations in those comparisons wrap as signed 32-bit values. The motion passes only when its elevation equals the required value. Band edges belong to elevation zero; they do not pass either outer band.

Arc admission reads both actors’ ordinary local origins and the receiver’s local heading, without attached or linked query-position substitution. It subtracts receiver position from target position in each coordinate with signed 32-bit wrapping subtraction and arithmetic-shifts each difference right eight bits. The bearing input is ordered (delta_z, delta_y, delta_x) and normalized to signed Q16 using the authored-location normalization. The normalized vector uses the signed polar lookup described by camera orientation: its positive first axis is a quarter turn, its positive third axis is zero, and the lookup result is reduced by half a turn and wrapped modulo 2048. A zero horizontal vector yields 1024. Let a be the absolute wrapped heading difference between the receiver heading and that bearing, and let c be the motion’s arc centre plus 512. The test passes only when c + arc > a and c - arc < a, using signed 32-bit wrapping arithmetic for the bounds. It does not halve the configured arc or include either boundary.

Defence start admission

The starter dispatch admits kinds zero through six and kind eight only when the corresponding receiver attack slot is populated. Kind seven and values outside zero through eight do nothing. Admission differs by kind:

• Kind zero, three, five and six require no selected move.
• For a nonplayer receiver, kinds one and two do not require an idle selection. For the selected player, kind one requires selected move zero and kind two requires selected move one.
• Kinds four and eight require zero combat cooldown, neither drawing nor sheathing, and no selected move.

An admitted start first writes its kind into the defence selector, then selects that move, then invokes the defence executor with request zero synchronously. The executor can therefore change state before a later picker or starter reads it. It resolves the defence selector through the receiver’s nine attack slots and uses the move selector to choose that attack’s motion. When the actor leaves the expected animation group, a populated following motion admits the next chain step, up to the third motion. The test reads the following motion’s first word, not the current one’s. Motion loading stores one in that first word for every motion it fills, whatever the authored type is (the authored type lives in a separate field), and unfilled motion slots keep their zero-initialized word. A combo therefore chains through all of its referenced moves. For selected-player kind four, the movement update precedes those writes and uses attribute 16 shifted left eight bits with movement mode one. Its return value does not gate the subsequent defence start. The nonplayer kind-four path omits that movement update.

When the defence executor starts or advances to a new motion, it requests the animation group, then sets the animation record’s finite loop countdown to one. This is the same countdown used by PushAnimation and the animation interpreter. The move selector is written before the animation request. After the request and loop-count write, a start clears target mark 0x10, sets executor state one, raises intent bit one, clears mask 0x20 and subtracts ten from aggression, then synchronously requests a type-one timed taunt. A chain step clears the target mark, raises intent and subtracts ten before clearing mask 0x20; it does not request another type-one taunt. Animation services therefore run before these combat-state changes, and the taunt service sees the committed start state.

DisableHook and EnableHook

DisableHook sets and EnableHook clears mask 0x02 of the receiver’s script-control byte (the native-hook suppression flag above) and changes nothing else. Both take no arguments and return zero.

GetFramePassed

GetFramePassed takes no arguments and returns the shared whole nominal-tick increment of the current update (the same value the elapsed-time tasks consume).

ShowItem and ShowItemNoRtx

ShowItem(item, text, first, second) and ShowItemNoRtx(item, first, second) return zero and only leave a request for the main loop’s item viewer. Each stores the item identifier and the two trailing words and marks a request pending. ShowItem ignores its second argument and leaves the viewer’s no-text flag as it was; ShowItemNoRtx sets that flag. The flag stays set until the viewer consumes the request. The handlers perform no display and read no inventory state.

ViewGXA

ViewGXA(name, frame, count) is a task that shows one installed GXA image over the world frame. name is a file name relative to the game directory (the shipped scripts name system\stmap01.gxa through stmap17.gxa and system\mirror1.gxa through mirror3.gxa), frame selects the image within the file and count is the number of task counter ticks. The first invocation (counter zero, nothing loaded) loads the file. Every invocation whose counter is below count - 1 places the selected frame centered on the 640 by 480 screen (x is half of the 640 minus the frame width, y half of the 480 minus the frame height), clears the second image slot and stays active. The invocation at counter count - 1 or later discards the image, clears the drawn-image pointer and completes, so the image is drawn for count - 1 frames (the same completion test as Wait). The main loop draws the pending image after the world frame.

DropAllItems

DropAllItems takes no arguments and returns zero. When the task system is enabled it applies the DropItem routine to every item id from zero up to the item count, each with the count currently owned, in ascending order, and then clears the selected item. Ids with a zero count are skipped. Each id must have an ITEM.INI definition; the shipped file defines ids 0 through 86 without gaps.

InRectangle

InRectangle(x1, z1, x2, z2) returns one when the receiver’s query position lies inside the rectangle on both horizontal axes, otherwise zero. The query position is the attached pose for an attached receiver, the linked position when one exists, and the local position otherwise (the same selection as the fighting query). Each pair of corners is ordered independently, so the corners may be given in either order, and the comparison is inclusive. The arguments use the position’s runtime units.

Camera initial state and player-type settings

At world load the camera actor and the alternate camera actor are both the CAMERA instance. The shared selection starts at slot zero and record zero is the selected record. Each record’s bound actor is the selected player. The stored bound-position history of record zero starts as the bound actor’s current position. The shared state block (transition word, scripted-camera active word and both published poses) starts zero until setup runs the full camera pose stage; its result then becomes both the current and the preceding published pose.

Record zero’s distance, minimum distance, target offset and position offset take the installed [camera] values listed in the record settings above when the selected player’s attr_player_type is not one. When it is one, they take a reduced set derived from the same keys instead:

Script light controls

Light, LightRadius, LightIntensity, LightOffset, LightFlicker, FlickerLight and LightFlickerOff act on the receiver’s light record and return zero. When the receiver has no record, the first call creates one: disabled and unlocked, offsets zero, intensity 256 and radius 100 (each current value equal to its starting value), flicker fields zero. LightOff does not create a record.

Map loading gives a type-4 object a record of its own: locked and enabled, with the placement’s intensity and radius as both current and starting values and colour zero (the placement’s colour is not copied, unlike for a type-6 object), so those objects’ first light call updates an existing record.

Every stored value keeps only its low sixteen bits.

Nonplayer combat taunt requests

The decision stage requests a taunt of a numbered type from the receiver’s taunt list (each record carries a type, a four-byte RTX label, and an animation value). A request is ignored when the receiver is dead or its list is empty, and when type 9 is requested while combat flag 0x40 is set.

Distance gate. For types other than 0, 2 and 6, a request with a combat target is ignored when the distance to the target is 0x40000 or more.

Busy gate. For types 10 and 11, the request is ignored while the receiver has a current taunt whose pending field is set.

Types 0, 2, 6, 10 and 11 use the in-order scan with the one-in-four random stop described in the taunt selection rules, including the death fallback to the hurt type here expressed as: when nothing matched for type 6, the request repeats as type 2.

All other types, including 1, 3, 4, 5, 7, 8 and 9, consume fifteen draws, each choosing a list index draw * count / 32767, even after a record has been selected. A probed record of the requested type with a nonzero label becomes the choice when no choice exists yet, or otherwise replaces it when (combat value + clock sample) mod 2 is zero. The combat value is the combat record’s retained allocation index. The decision stage caches the current 32-bit clock sample. In normal clock mode this is the raw BIOS-clock sample, interpreted as a signed value, rather than a nominal-tick increment or accumulated nominal ticks. Their sum wraps as a signed 32-bit value. The taunt is then presented only when (combat value + clock sample) is a multiple of the combat record’s signed taunt period, initialized to 129 - attribute 87; presenting a type 9 taunt also sets combat flag 0x40.

Presenting a taunt replaces the current taunt reference in the combat record.

PlayAnimation

PlayAnimation(group, modifier) in its function form requests an animation group for the receiver and returns zero without waiting (unlike PushAnimation, which is a task). The request goes through the ordinary request arbitration with the modifier narrowed to one byte. It does nothing when the animation system is disabled, when the receiver has no animation state, or when the receiver is excluded from ordinary object updates.

The installed BAT and DOORBAT scripts also pass this native through the multitask encoding. The void native does not assign a stable result register in that entry path, so its multitask completion value is unspecified; the function-form zero result does not define multitask slot completion.

Candidate collection for an ordinary update

When ordinary traversal reaches an actor whose collection flag is set, it fills the engine’s retained candidate model list before running that actor’s update (native hook, combat decision and script stages included). The list holds the models inside a sphere centred on the actor’s position, with the actor’s own model excluded. The sphere radius is twice the stored radius of the actor’s current model, rounded to the nearest integer, or 200 when the actor has no model. The collector keeps at most 64 entries. Queries made later in the same update (the in-sight test and the nonplayer movement probes) read this list without collecting again.

Nonplayer blocked-ahead probe

The movement helpers used by the combat decision ask whether the space ahead of the receiver is blocked by distance. The probe applies only when the receiver has a combat record and its current animation group has class one. It forms a local offset with X zero, Y equal to (positive Y extent of the actor's body - SYSTEM.INI post_collide_height - distance) in eight-fractional-bit units, and Z equal to -14336; rotates it by the actor’s matrix; and adds the actor’s query position. The resulting single point (radius zero) is tested against each model in the actor’s candidate list: any contact blocks. Candidates are typed by source: static placements and the secondary list carry type 0x20, actor-owned models carry type 0x80. While the actor’s queued-motion byte is 0x18 (24), actor-owned candidates are skipped, so only static models can block.

Session requests: LoadWorld, WonGame, PushPlayer and PopPlayer

LoadWorld(world, marker, heading), WonGame, PushPlayer and PopPlayer return zero and only record a request; the main loop acts on it after the current script step. LoadWorld retains its three integers. The main loop then loads the world: the world index must be 0 through 99 and name a WORLD.INI entry (otherwise loading ends with an error), the current-world index becomes that value, the selected start marker (the second argument) supplies the player’s starting position triple, and the third argument, masked to 0 through 2047, supplies the starting heading. The three words are cleared when the load begins. WonGame, PushPlayer and PopPlayer each set one request flag for the main loop, which consumes them. WonGame ends the world loop and starts the ending.

PushPlayer and PopPlayer are consumed at the end of a world-loop iteration that does not leave the loop: push first, then pop. Each clears its own flag when consumed, whether or not it acts. The engine keeps the CYRUS and GREMLIN player records and one swap state, clear in a fresh world. While the swap state is clear CYRUS is the selected player and GREMLIN is excluded from ordinary object updates; while it is set GREMLIN is selected and CYRUS is excluded. The world loop re-asserts that selection and exclusion every iteration.

• PushPlayer acts only while the swap state is clear. GREMLIN becomes the selected player, the swap state is set, and GREMLIN takes CYRUS’s player transfer (below). GREMLIN stops being excluded from ordinary updates and CYRUS becomes excluded.
• PopPlayer acts only while the swap state is set. CYRUS becomes the selected player again, the swap state is cleared, and CYRUS takes GREMLIN’s position, heading and retained movement state with the same exclusion exchange reversed. CYRUS then receives an ordinary animation group request for group 0, issued twice.

A second PushPlayer while swapped, or a PopPlayer while not swapped, only clears its flag.

The player transfer copies from the role that was selected to the role that becomes selected: the local position, two further triples of 32-bit words at offsets 0xFB and 0x108, the three angles, which the orientation setter masks to 0 through 2047 and also stores as the creation angles (start_angle, offset 0x144) and the previous-angle history (last_angle, offset 0x150) before it rebuilds the orientation matrix, the four motion bytes at +0x1B1 through +0x1B4 (the last is the living state), the 32-bit word at +0x1CD, the two words at +0x08 and +0x0C, and byte 3 of the attribute block (the health attribute). It zeroes the words at +0xC7 and +0x25, re-registers the new role in its map cell, and clears the new role’s object-update exclusion byte while setting the old role’s.

KillMe and Resurrect

KillMe and Resurrect take no arguments, act on the receiver and return zero. Both first release the receiver’s two held walk-node reservations: a reserved node is cleared only when its recorded owner is the receiver, and both reservation slots then hold no node.

KillMe then clears the receiver’s current model presentation record, releases its two retained per-actor buffers, sets its killed flag and its death selector to 8, and stops every active sound owned by the receiver. The two buffers are the receiver’s light record (41 bytes) and its 20-byte flat sprite record, the record the Flat functions control: an enable byte, a pending byte, three 16-bit offsets, the texture identifier, a frame cache and the playback counters. Each pointer is cleared after its buffer is freed, so a later light or flat call creates a new record with the defaults.

Map loading creates a flat record for every type-3 placement, enabled, with zero offsets and the placement’s texture value as its texture. While a record is enabled and its texture is nonzero, the ordinary actor drawing traversal draws the actor’s flat as a camera-facing sprite at the actor’s position plus the offset resolved through its orientation, using the texture’s attributes for its flags and alpha. The installed type-3 placements are the LAVABUB1 lava bubbles (DRINT, ISLAND, CATACOMB) and the LH_FIRE and CT_FIRE fires.

The drawing routine runs once per actor in the ordinary traversal, for actors whose draw-suppress byte is clear. It draws nothing unless the record’s enable byte and texture identifier are nonzero. The three signed 16-bit offsets are transformed by the actor’s current pose, and the integer result (the transformed point shifted right by eight) is the sprite’s world position. The record caches the loaded image slot for its texture; while that cache is zero it is filled from the texture identifier, and a zero slot or one above 30000 is a fatal error. The texture’s attribute record, when present, gives the draw flags (the flag word is 1 plus the attribute’s flag byte) and the alpha (the attribute’s alpha byte plus one); without it the alpha is 255. The sprite is then submitted through the same routine as placed flats with the cached slot, the record’s frame word, the position, scale 1 and those flags and alpha, with the world’s world_ambientfx value (see WORLD.INI) as the brightness. When flag 0x80 is set the flag word also gains 0x200 and the brightness, alpha and size inputs are replaced by 200, 200 and 200, which that submission reads as a solid-colour tint (red, green and blue all 200).

Each update of an actor that is not hidden also steps its flat record, beside the light maintenance. A zero or 0xffff texture disables the record. A disabled record adds the elapsed ticks (low byte, wrapping) to its pending byte and is freed once that byte exceeds 32. An enabled record first consumes a wrap marker (the high bit of its loop byte): the marker clears and the frame returns to the record’s counter. A frame of 0xffff, or a counter equal to the last frame, shows a static image. Otherwise the frame moves by the elapsed ticks times the speed byte, up when the counter is below the last frame and down when it is above. Passing the last frame disables the record when the loop byte is zero; otherwise it sets the wrap marker and restarts the frame at the counter plus the overshoot (clamped to the counter if that still passes the last frame).

Resurrect acts only while the killed flag is set or the death selector is 8; otherwise nothing further happens. It clears the killed flag. When the receiver has combat state and its death selector is 6, it first sets the selector to 1 and the death response to 0, clears combat flag 0x04 and zeroes the close-distance pass counter and the attacker selection state (the unconditional part of the end-of-combat reset); a receiver that KillMe just killed has selector 8, so Resurrect leaves its selector unchanged. With combat state it then re-initializes that state from the receiver’s attributes.

Removal of killed created objects

Each world-loop iteration, before the family update, removes every object that was created after the world loaded (it has no map object) and whose killed flag is set: it leaves its map-cell list and the actor table, its KillMe cleanup runs again and its record is freed. A killed map actor stays allocated; the ordinary actor update skips killed actors.

projectileAI

projectileAI is a task without arguments; its update runs on the receiver, a created object whose parent is its creator. The update returns one to keep flying and zero to end the task:

1. The speed is the receiver’s attribute 8 shifted left by eight, multiplied by the frame scale and shifted right by eight (signed). The previous local position is saved, then the offset (0, 0, speed) rotated by the receiver’s pitch, yaw & 0x7ff and roll is added to its local position.
2. A distance from the parent of 0xbb800 (Q8) or more ends the task, keeping the moved position. The distance is the single-precision magnitude of the X, Y and Z differences rounded to nearest-even; it is zero without a parent.
3. When the world has terrain and the receiver’s Y is strictly greater than the terrain height at its integer X/Z (the terrain support sample, times 256 and rounded), the previous position is restored and the task ends.
4. Candidates are gathered around the receiver’s position with the radius attribute 8 (map units), excluding the receiver’s own model, by the live and transient candidate rules (static placements, ordinary actors, transient models). The segment runs from the previous to the new position, both shifted right by eight.
5. Every face-model candidate not owned by the parent is queried with that segment, without polygon sidedness. A segment that ends exactly on a face plane does not cross it. Over all contacts, the one with the smallest rank (strictly less than 0x7fff and every earlier rank) is kept. When any contact exists, the receiver moves to that contact’s integer point shifted left by eight and the task ends.
6. Otherwise every actor-style candidate except the parent is tested in candidate order with the actor’s collision spheres. A sphere is hit when either segment endpoint lies within its radius (squared integer distance computed in single precision and rounded, compared with the squared radius). The spheres are the actor’s RAVC records (flag 2 always, flag 4 only while the actor’s current animation group pair matches the record), followed, unless attribute 56 is nonzero, by the actor’s ordinary collision shape spheres; each center is rotated by the actor’s orientation and added to its position. At most 128 spheres take part.
7. On the first hit, an actor with combat state is sent combat message 0xd005 from the parent; with or without combat state, the previous position is restored and the task ends. Without a hit the task continues.

InKey

InKey(code) returns one when a keyboard key is down and zero otherwise. The low byte of the argument is a character; its key is found by matching the character against the keyboard table’s unshifted and shifted characters, and a character with no table entry returns zero. The next three bytes each name a required modifier by a character, either case: s Shift (either shift key), c Control and a Alt; the result is zero when a named modifier is not held. Otherwise the result is one when the key’s state word is nonzero or the key is the latest key event the keyboard handler recorded. The debug shell reads it for the letters p, c and d and for Alt+q, and a few bridge and door scripts read r.

GolemSteam and DragonBreath

GolemSteam takes no arguments and returns zero. A receiver excluded from object updates does nothing. Otherwise one Rnd(4) draw that is not zero ends the call. On zero a second Rnd(4) draw selects one of the receiver’s four RAEX attachment vertices in the order grip0, scabbard1, grip1, scabbard0. The vertex, rotated by the receiver’s orientation and added to its position, becomes the point of a steam effect: descriptor 0x32480 when the world-loop frame counter is odd and 0x22480 when it is even, with speed one.

DragonBreath takes no arguments and is also the update of the multitask DragonBreathTask, which completes when the update returns zero. It acts on the receiver, a dragon with combat state:

1. A receiver whose death selector is 8 returns zero. First, when the player holds item 0x4b with a nonzero count, one unit of item 1 is added, the player’s held-item attribute (23) becomes 1, item 0x4b is emptied and item 1 becomes the selected item.
2. One Rnd(4096 / frame scale) draw of zero, while a dialogue line owned by the receiver is active, spawns the smoke effect 0x32480 at an attachment vertex: scabbard0 when a following draw masked with one is nonzero, else scabbard1 (rotated and offset as for GolemSteam).
3. A nonzero fireball cooldown, a process-wide counter that starts at zero, is reduced by the nominal ticks of the frame (to zero at the least) and the update returns one.
4. Without combat flag 0x04 or without a combat target the update returns one. A target whose rounded 3-D distance is less than 0x19000 (Q8) also returns one.
5. Otherwise the fireball is created: an object of the installed script DRAGBALL whose parent is the receiver, at the rotated grip0 vertex plus the receiver’s position. Its orientation is the aim from grip0 to grip1: yaw is the bearing of the horizontal difference plus 1024; the pitch is the elevation of the difference minus 512, then 120 - pitch, all masked to 2047; roll is zero. The cooldown becomes Rnd(32) + 12 and the update returns one.

Nonplayer deep-water and edge probe

The strafing steppers (MoveLeft, MoveRight) and MoveForward call one probe before they move. It applies only to receivers whose surface byte is 2 or 4 (the deep-water classes); every other receiver passes. The probe point is the receiver’s position plus a step of 16384 (units of 1/256 map unit) along the direction chosen by the motion-direction byte (2 and 6 forward, 3 and 7 backward, 4 left, 5 right, any other value forward), rotated by the receiver’s heading. The point is looked up in the terrain material rules of terrain material blend coverage.

The probe fails (blocks the move) only when the resolved surface is 10 with blend coverage 0 and the terrain slope class at the point is 2. A point with blend coverage 256, a point with partial coverage (surface 3), a point without terrain, and every other surface pass. The slope class is the classification of the terrain face normal as for ground support. A failing probe returns zero to its caller.

Nonplayer step hazard

The step hazard test answers whether moving a nonplayer receiver to a destination lands on a steep surface. It applies only to receivers whose attribute 1 has bit 1 set; others never report a hazard. The surface at a point is resolved with a vertical segment of the post-collide height about the point’s centre (the point’s Y plus the receiver’s positive Y extent) against the candidate models and the terrain. Among the contacts, only floor (class 4) and steep (class 2) surfaces compete, and the one whose rank is nearest 0x4000 wins; the terrain replaces that surface when the segment’s top is at or below the terrain height and the model surface is farther from the destination’s centre than the terrain is. A point with no surface counts as class 1, and when neither the destination nor the current position has a surface the result is no hazard. The class comes from the contact normal’s Y (scale 256): at most -161 is 4, at least 161 is 8, at most -42 is 2, otherwise 1. The test reports a hazard when the destination’s class is 2.

The selected player runs the same test, except that it reports no hazard while the player’s support-history counter is nonzero.

MoveForward

MoveForward(duration) is a task that steps the receiver forward along its heading. It shares MoveBackward’s result and movement rules except as listed here.

Admission. The call completes without moving when the receiver’s rope attachment, sliding state, falling state or queued-motion byte is nonzero. There is no lifecycle-byte test. While the two-bit step counter in the receiver’s motion byte (bits 4 and 5) is below three, the forward step check must also pass: it passes when the lifecycle byte is 7 and attribute 1 has bit 0 clear; otherwise it fails when the receiver’s attribute 1 has bit 1 set and the step hazard at the destination reports a hazard, where the destination is the receiver’s position moved forward by half of attribute byte 8 (whole units, times the frame scale, arithmetic shift right eight). A failed check completes the call. Admission then stores motion direction 2.

Combat stance (the receiver holds a weapon or its combat flag 0x04 is set). The call completes without moving when the receiver already has a selected combat move. Otherwise the group is 92 and the step length is attribute byte 17.

Outside combat stance. In deep water (surface 2 or 4) the edge probe must pass, the group is 142 and the distance is halved; otherwise the group is 30 while a torch burns and 18 when not, with step length attribute byte 8.

Animation and movement. The call completes without moving when the receiver has no entry for the group. Otherwise the group is requested as PlayAnimation(group, 0) does, and with the animation system enabled and the current group not the requested one the call waits like MoveBackward. The movement heading is the receiver’s local Y angle (no offset) and the distance is the step length in whole units times 256, scaled and translated as for MoveBackward.

Forward movement amount query

Fight spacing’s forward amount query shares the forward startup counter and step-called state with actual movement. It refuses nonzero rope attachment, sliding, falling, queued-motion or living-state values. Below startup counter three, it requires the forward step check to pass. It then stores motion direction 2.

A held weapon or combat flag 0x04 selects group 106 and attribute 16 for action selector 4, or group 92 and attribute 17 otherwise. Outside combat stance it selects attribute 8 and group 142 in deep water, group 30 with a burning torch, or group 18 otherwise. It requests the group with frame zero. When animation is enabled and the requested group is not current, it returns the ordinary duration continuation result without marking forward called or advancing the counter.

Once animation permits the step, it marks forward called, multiplies the selected step byte by 256 and halves that distance in deep water. Below counter three it applies the ordinary startup adjustment and increments the shared counter. With translation suppression clear, its return value is the signed wrapping product of that adjusted amount and frame scale, shifted right eight. With suppression set, it instead returns the adjusted amount without frame scaling. It does not translate the receiver. A subsequent movement request therefore reads the counter and animation state changed by this query.

WalkForward

WalkForward(duration) delegates to MoveForward(duration) in deep water before checking its own admission state. For a nonplayer receiver outside deep water, a rope attachment, sliding state, falling state or queued motion refuses the call. The walk-forward step check must pass before motion direction 6 is stored.

The walk-forward step check refuses a rope attachment. It passes immediately for a receiver whose lifecycle selector is 7 and whose attribute 1 has bit zero clear. Otherwise it builds a destination from the local offset [0, 0, (attribute12 + positive_z_extent) * 256], with signed wrapping arithmetic, rotated by the receiver’s stored matrix. It adds the rotated X/Z to the receiver’s position and retains the receiver’s Y coordinate. It requires the destination body-contact test to pass, the step-hazard result to differ from one, then the additional destination-admission test to pass, in that order. A failed test sets bit 0x80 in the receiver’s step-status byte and returns false. Early rope refusal and lifecycle acceptance leave that byte unchanged. The step’s destination support test passes whenever attribute 1 bit 1 is clear. The additional destination-admission test runs the ordinary collision pass with the receiver temporarily at the destination. It restores the original position afterwards, while retaining other collision writes.

A held weapon or combat flag mask 0x04 selects animation group 31 and attribute byte 19 as the step length. Outside combat stance, a burning torch selects group 21 and otherwise group 20; both use attribute byte 12. A missing group skips animation requests and translation, while duration completion is still evaluated. An available group is requested with frame zero. With animation enabled, a different current group waits without advancing the step counter or translating.

The initial movement distance is the selected step length multiplied by 256. When that length is zero, the initial distance is instead half of attribute byte 8, without the multiplication by 256. While the two-bit step counter is below three, the existing step-distance adjustment runs and the counter increments. Animation translation suppression prevents movement after that adjustment. Otherwise, signed wrapping multiplication by frame scale followed by arithmetic shift right eight gives the distance. Positive distances translate along the receiver’s local Y heading, masked to 2047. Duration completion follows MoveBackward.

MoveLeft and MoveRight

MoveLeft(duration) and MoveRight(duration) are tasks that strafe the receiver. They share MoveBackward’s admission, result and movement rules except as listed here. Admission is identical. A call stores motion direction 4 (left) or 5 (right) once admitted.

Combat stance (the receiver holds a weapon or its combat flag 0x04 is set). The call completes without moving when the receiver’s current group is already the strafe group (94 for left, 95 for right, or either of the two) or when the receiver has no entry for the strafe group. Otherwise it requests the group as PlayAnimation(group, 0) does, then turns the receiver’s heading: the left call subtracts, and the right call adds, attribute byte 84 times the frame scale (arithmetic shift right eight), wrapped to 2047. The movement heading is that new heading plus 512 (left) or minus 512 (right), wrapped, and the step length is attribute byte 83. No safety check applies.

Outside combat stance. The call completes without moving when the lateral step check fails (the destination of a step of attribute byte 10 plus the receiver’s retained step value, to the left or right of the heading, fails the model contact test). In deep water (surface 2 or 4) the edge probe must also pass and the group is 143; otherwise the group is 25 left or 27 right while a torch burns, else 24 left or 26 right. When the animation system is enabled and the receiver’s current group is not the requested one the call waits like MoveBackward: one while duration - 1 > elapsed, zero otherwise, without moving. With the lifecycle byte 15 (hanging at an edge) the call instead runs the lateral edge test and requests group 28 left or 29 right. The movement heading is the receiver’s heading plus 512 (left) or minus 512 (right) and the step length is attribute byte 10.

Movement and result. The shared step counter, translation-suppression marker, frame scaling and result are those of MoveBackward.

Fight-spacing directional admission

The left, right and backward destination checks used by fight spacing refuse a rope attachment before reading geometry. They accept immediately when lifecycle selector 7 has attribute 1 bit zero clear. These early results leave the receiver’s step-status bytes unchanged.

Otherwise, each check builds its directional local offset with signed wrapping arithmetic:

It rotates the offset by the receiver’s stored matrix, adds the rotated X/Z to the local position and preserves the receiver’s Y. It requires a nonzero destination body-contact result, a step-hazard result other than exactly one, then a nonzero additional destination-admission result, in that order. A failed stage skips the later stages and returns zero. Failure ORs 0x20 into the step-status byte for left, 0x40 for right, or 0x01 into its companion byte for backward. Success returns one without clearing retained status bits. The checks themselves do not replace the receiver’s position.

MoveBackward

MoveBackward(duration) is a task that steps the receiver backward relative to its heading. Each invocation returns zero (complete) or one (continue); it reads the task’s elapsed input.

Admission. The call does nothing, completing immediately, when the receiver’s rope attachment, sliding state, falling state or queued-motion byte is nonzero, or its lifecycle byte is not 0 (byte 15 is refused too, unlike the strafes). Otherwise it sets the receiver’s motion-direction byte to 7.

Animation. The receiver is in the combat stance when it is holding a weapon or its combat flag 0x04 is set. In combat stance the blocked-ahead probe runs with distance 30; a blocked probe completes the call. The group is then 93 and the step length is the receiver’s attribute byte 18. Outside combat stance the group is 143 in deep water (surface value 2 or 4), 23 while a torch burns, and 19 otherwise, with step length attribute byte 9. When the receiver has no entry for the group, the call skips the rest and uses the final duration test below. Otherwise the group is requested as with PlayAnimation(group, 0). When the animation system is enabled and the receiver’s current group is still not the requested one, the call returns one while duration - 1 > elapsed and zero otherwise, without moving.

Movement. The heading is the receiver’s local Y angle plus 1024, wrapped to 2047. The distance is the step length in whole units times 256. A two-bit step counter in the receiver’s motion byte (bits 6 and 7) selects an initial-distance adjustment while below three, then increments. The adjustment reads attribute byte 11 independently of animation translation suppression. For input distance d, it follows this table. Products wrap as signed 32-bit integers, right shifts are arithmetic, and division truncates toward zero.

At counter three the distance stays unchanged. The packed byte holds left, right, forward/walk and backward counters in consecutive two-bit fields, from least to most significant. Each direction has a shared called flag, reset at ordinary wrapper entry. At ordinary update cleanup, a direction’s counter is cleared only if its called flag is zero; called directions retain their counters. Directional displacement and sliding mark this same packed byte, saturating the selected direction’s counter rather than writing a separate movement record. Collision rollback can separately clear the packed byte when restoring the previous position. Entering collision processing does not unconditionally clear it.

Unless the animation’s translation-suppression marker is set, the distance is multiplied by the frame scale (arithmetic shift right eight) and, when positive, the receiver’s X and Z move that far along the heading by the heading-based translation rule.

Result. One while duration - 1 > elapsed, otherwise zero.

WalkBackward

WalkBackward(duration) is a task. In deep water (surface value 2 or 4) it runs MoveBackward unchanged. Otherwise it follows MoveBackward’s animation, movement and result rules with these differences.

Admission. The call completes immediately when the receiver’s rope attachment, sliding, falling or queued-motion byte is nonzero or its lifecycle byte is not 0. For the selected player it also completes immediately while a retained player-mode word equals one and the queued-motion and falling bytes are both zero. It then runs the backward form of the ordinary directional step check, which uses attribute byte 13, and completes when that check refuses. Only then does it set the motion-direction byte to 7.

Animation. In combat stance the group is 93 and the step length is attribute byte 20. Otherwise the group is 23 while a torch burns and 22 otherwise, with step length attribute byte 13. There is no blocked-ahead probe.

Movement. When the step length is zero, the initial distance is attribute byte 9 shifted right by one, not multiplied by 256; the step-counter adjustment and frame scaling then apply as for MoveBackward.

Actor animation playback

Actor animation selects polygon-mesh frames through RAAN references and RAGR command groups. Model frames contain vertex animation, not skeletal animation.

Model and frame selection

A file ShowFrame command uses an unsigned twenty-bit reference into the actor instance’s frame table. Each RAAN entry contributes the indicated number of model frames, starting at zero, in entry order. The loader resolves the reference to a runtime model handle and frame index and patches those two values into ten-bit command fields. Playback stores that pair as the actor’s current pose. It does not interpret the second value as an attachment vertex.

Placed-object frame sources

RAAN is not the only source of an instance’s frame table. After initializing a type-1 MPOB object, the loader uses its model_name when the instance has no frame table, its static-model flag is clear, and the name is nonempty.

• An MPOB is_static value of 1 selects the static model path and leaves no animation frame table.
• Other values select the animated model path. The byte is the number of frame-table entries, each referring to that model and successive frame indices starting at zero. A zero value allocates an empty table.

The group loader installs the actor definition’s RAGR groups only when the instance has a frame table and its static-model flag is not set. It resolves ShowFrame operands against that instance’s table and rejects references outside the table. RAGR commands can therefore exist in a definition without becoming runtime animation groups for a particular placement. Instances sharing one definition can obtain their frames from different placed models.

Animation tasks

PushAnimation(group, count) requests the group if it is not yet current. When the group becomes current, the task sets its byte loop countdown to count. It remains active while that group is current and completes when the group changes. Thus count is a finite loop input, not a speed or wall-clock duration. The animation request made by this task has a speed modifier of zero.

The current group is read as a signed sixteen-bit value and compared with the complete thirty-two-bit group argument. This comparison does not first narrow the argument to sixteen bits. The loop count stores only the low eight bits of its argument. Changing the count operand after the task enters its started phase does not rewrite the countdown; that phase only compares the current group with the reevaluated group operand.

The first invocation has a separate not-started phase. If the requested group is not current, it makes an ordinary request and remains active. Even when that request starts the group immediately, this invocation does not set the loop count. A subsequent invocation that finds the group current sets the byte count and enters the started phase, still returning active. Once started, it completes only when the current group differs; it does not re-request the group. An initial invocation that already finds its group current sets the count immediately and remains active. Each invocation evaluates the call’s operands again. Task creation and later task invocations are separate scheduling stages.

The task does not test whether the requested group exists. Ordinary request fallback still applies, but selecting the default does not change the task’s requested group. While that requested group is not current, the task remains in its not-started phase and makes another ordinary request on each invocation. A missing group therefore does not by itself complete the task.

For forward playback, GoToPrevious with a nonzero loop countdown decrements that countdown. If it becomes zero, playback continues after the command; otherwise it jumps to the command’s target. With a zero countdown it jumps without decrementing. GoToFuture continues past itself while a finite loop countdown is nonzero. With no countdown, a pending transition or the animation’s exit flag can make it take its target instead.

The group header currently called anim_id supplies the animation’s byte frame countdown. An animation request adds its speed modifier to that value. This is separate from the task’s loop countdown.

Frame waits

WaitAnimFrame(group, frame) inspects the receiver’s animation state. WaitPlayerAnimFrame(group, frame) applies the same test to the currently selected player, independently of the task’s receiver. Either task completes when its inspected actor or animation association is absent.

If neither the current nor pending group matches group, the task completes. If only the pending group matches, it keeps waiting. When the current group matches, it completes once the unsigned byte anim.real_frame is greater than or equal to frame; otherwise it keeps waiting. This counter is distinct from the anim.frame command cursor and the selected model-file frame.

Selecting a new group resets anim.real_frame to zero. Ordinary frame advancement increments it when the frame countdown expires, and each skipped ShowFrame increments it again. The byte wraps from 255 to zero. A zero-tick update or a countdown decrement that retains the same frame leaves it unchanged.

Command processing has a separate signed sixteen-bit cursor. It indexes the packed command table and remains on the command displaying the current frame. Selecting a new group resets it to zero. BreakPoint and DelayCounter advance that cursor without incrementing anim.real_frame; a GoToPrevious backward jump assigns its command target without resetting the counter. Combat timing queries read this signed cursor, rather than anim.real_frame.

Current and pending group values are signed sixteen-bit values compared with the full script integer argument. The frame threshold also remains a full script integer; neither argument is narrowed before comparison. These tasks read the current state on each invocation without requesting or advancing animation, changing actor state, or calling another native handler.

Ordinary requests and default groups

An actor keeps a current group, one pending group, and a default group. Ordinary requests do not form a queue. When the current group is the default, requesting the default again returns without restarting it. Requesting another group clears the current group so that the new request can start immediately.

Otherwise, an ordinary request replaces the pending group when there is no current group, no pending group, the pending group number is less than or equal to the requested number, or the pending group is the current group. A lower number cannot replace a higher pending number outside those cases.

An absent requested group falls back to the actor’s default group if that group exists. If neither exists, the pending request is cleared. The accepted group’s low header byte plus the request modifier becomes its byte countdown, with byte wrapping. A request with no current group invokes animation advancement immediately using the existing shared tick input; it does not invent a tick.

When neither a current nor pending group exists, advancement requests the default group with modifier zero. EndAnimation clears the current group and invokes advancement again, so a pending request or the default can start in the same update. Treating End as a permanently stopped actor loses this behavior.

Forced requests, group-type interruption rules, actor eligibility, and the number of advancement calls made by an actor update use additional rules. Request arbitration does not activate placed actors automatically.

Placed actor initialization and eligibility

New actor animation state initializes its default group to zero. For a placed object with MPOB type 1 and an animation model table, group setup builds the RAGR table and makes two ordinary requests for group zero with modifier zero. These requests reuse the shared nominal ticks.

The actor loader chooses its model path from the RAHD record. A zero raan_count means no model. Otherwise, the static-model shortcut applies when raan_count is one, the complete signed anim_control_prefix field is −1, and the signed anim_frame_data field is less than two. All other nonzero-model cases build the animation model table. This classification precedes group requests and the model-path message-group attribute assignment. Exported actor metadata records the result as model_load_path: none, static, or animation_table.

The MPOB activation byte selects storage and update-list membership. Zero stores an ordinary placed actor in its spatial map cell; a nonzero value uses the persistent actor list. The active update list combines nearby cell actors with that persistent list. A zero activation byte therefore does not mean that an actor can never animate.

Cell assignment uses the decoded MPOB X/Z coordinates directly, with 512 coordinate units per cell. The runtime position has eight fractional bits; shifting that position by eight recovers the decoded file coordinate. The three-byte MPOB coordinate itself is not divided by 256 again.

The cell window starts nine 512-unit cells before the supplied horizontal center, clamped at the map edge. The main loop supplies the current view coordinates, not the actor body position. It spans eighteen cells per axis, omitting its four corners. The inner sixteen by sixteen cells include ordinary actors. On the outer border, actors with a nonzero attribute byte 113 are excluded. Debug and global object-processing switches can further restrict this list. Membership alone does not make an actor eligible for an update; its runtime exclusion, pause, state and script checks still apply.

Cells are visited in increasing X within increasing Z rows. Eligible actors retain their current per-cell linked-list order; the persistent actor list is appended after the cell actors. New cell actors are inserted at the front of their cell list, and new persistent actors at the front of the persistent list. Consequently, actor creation order is not ordinary update order.

For each view coordinate, the window origin is zero below 4608, 56319 when the coordinate plus 4608 exceeds 65535, and otherwise the coordinate minus 4608. Dividing this origin by 512 gives the first cell. The regional update compares that starting cell with its cached entry and rebuilds the lists when they differ.

Moved actors enter a deduplicated deferred list in first-registration order. The frame loop consumes this list before regional actor selection, clearing its entries and count after the pass. Map-excluded script context suppresses relocation; pooled persistent actors also retain their existing membership. For a cell actor, relocation uses its linked position when present, otherwise its local position. Each X/Z coordinate is shifted right eight bits and masked to 16 bits before selecting its 512-unit cell.

An unchanged cell retains list order. A changed cell unlinks the actor from its previous cell and prepends it to the destination cell. After a cell change, the rounded horizontal distance from the camera to the actor’s local position, shifted right eight bits, invalidates the cached regional list when it exceeds 3584. Nearby relocation retains the cached traversal until another rebuild condition applies. Removing a queued actor clears its pending entry.

Ordinary default selection can use attribute byte 44, but combat, injury, attachment, movement and player-specific states can select other groups. Changing the default can force an immediate replacement when the old default was current and had not reached an exit. It is not safe to select attribute byte 44 unconditionally for every actor.

The installed ISLAND map has three FLAG2 placements, all ordinary objects with a zero activation byte and no static model override. Their FLAG2 attribute record is all zero, including byte 44. These values define their initial state.

Living actor default selection

For an actor that does not satisfy IsDead, ordinary default selection uses these branches in order. The first matching branch wins.

The selected-player deep-water branch also invokes weapon-state cleanup; selecting group 141 alone does not perform that transition.

IsSheathingSword and IsDrawingSword require the item system to be loaded, an actor with animation state, and ordinary rather than shell execution. IsSheathingSword accepts actor state 21 or current group 129; IsDrawingSword accepts actor state 20 or current group 91.

IsHoldingWeapon returns false for an absent actor. For a present actor, nonzero attribute byte 110 returns true before the item-system, animation-state and shell checks. Otherwise it requires those three gates, combat capability, a set weapon-drawn flag, and a false IsSheathingSword result.

After selection, when animation state exists and execution is outside the shell context, a changed default replaces the current group immediately if the current group was the old default and its exit marker is clear. A pending group equal to the old default is separately replaced by an ordinary request for the new default. These checks use the old default captured before selection.

Combat entry

beginCombat uses the lifecycle selector read by IsDead, independently of the motion state used by weapon and living-default selection. On a nonplayer actor, it first sets script-control bit 0x02, including when the lifecycle selector already equals 6. A selector already equal to 6 skips the remaining entry work. Otherwise entry writes selector 6, handles weapon setup, sets combat flag 0x04, and requests the begin-combat taunt type 0, in that order.

Weapon setup checks attribute byte 23. When it is nonzero and animation group 91 exists, an actor whose weapon-drawn flag is clear runs weapon-draw admission and then immediately requests group 91 with modifier zero. An already drawn weapon skips both operations. When group 91 is absent, entry runs weapon cleanup, then sets the weapon-drawn flag and clears motion state to zero. A zero attribute byte 23 directly sets that flag and clears motion state, without weapon cleanup. These motion-state writes do not replace the lifecycle selector.

Weapon draw admission

Weapon-draw admission requires the item system, an animation state, no shell execution, no rope attachment, no motion state from 27 through 32, neither a draw nor sheath transition, no held-weapon predicate, no falling or queued motion, and motion state other than 15. For the selected player, attribute byte 105 equal to 1 also prevents admission.

After those gates, a nonzero held-item byte runs weapon cleanup. With a zero held-item byte, absence of assigned weapon state also runs cleanup. Otherwise edge motion states 10 through 19 and stored surfaces 2 or 4 prevent the draw. A successful draw sets motion state 20. For the selected player it also sets combat flag 0x04. DrawSword runs this admission for its receiver; the repositioning step that follows it in the routine is inactive in the shipped game, so a draw never moves the actor. This admission does not itself set the weapon-drawn flag.

Equipped-weapon transition

The equipped-weapon drawing pass requires the item system, an actor with animation state, ordinary execution outside the shell, and an assigned weapon. The actor’s weapon attribute selects an item of weapon type. Without combat state, this pass clears the drawn flag before processing motion state.

For motion state 20, the pass requests group 91 with modifier zero. While that group is current, its wrapping frame-progress byte is compared with attribute byte 35, attr_draw_frame. Before the threshold, the sheathed model is drawn. At or beyond the threshold, the held model is drawn, the weapon-drawn flag is set and motion state becomes zero. If group 91 is not current, the sheathed model is drawn and the transition remains pending.

For motion state 21, current group 129 uses attribute byte 34, attr_sheath_frame, as its frame-progress threshold. Before the threshold, the held model is drawn. At or beyond it, the sheathed model is drawn, the drawn flag clears and motion state becomes zero. A pending group 129 is cancelled when that transition completes. If group 129 is not current, the pass requests it with modifier zero and draws the held model. That invocation does not test the sheath threshold again, even if the request immediately makes group 129 current. Threshold processing resumes on a later drawing pass.

These transitions do not clear the companion motion byte. Outside these two motion states, a set drawn flag selects the held model. A clear flag selects the sheathed model, using the attached drawing path while group 129 remains current.

Weapon cleanup

Weapon cleanup restores the selected player’s stored playback-default group, with modifier zero, when its current group is 91 or 129. Other actors and other current groups do not receive that request. Motion state 20 or 21 is reset to zero together with its companion motion byte, independently of the drawn flag. The companion byte is separate from motion direction.

When the weapon-drawn flag is set, cleanup clears it and clears combat flag 0x04. For the selected player it also sets the health-candle show timer to 25 ticks. If the drawn flag was already clear, cleanup leaves the candle timer and combat flag unchanged.

Dead actor default selection

IsDead reads a runtime state selector rather than the health attribute. It succeeds when that selector is 8, or when the selected player’s death override is active. This selector is distinct from the actor state used by the living default-selection branches.

When ordinary default selection reaches the dead-actor branch, an actor with combat state takes its default group from that state’s death-animation selection. Without combat state, it selects group 123 when that group exists, otherwise group 124. Group existence requires an animation state with a populated entry for the requested group.

Animation-table setup clears the actor’s combat-state association and creates combat state when attribute byte 14 is nonzero. This state is separate from the animation group’s playback cursor and from the actor’s attribute table. The combat record’s death-animation selection starts at zero; constructing the record does not copy attribute byte 44 into that selection. A newly allocated combat record receives the next combat index. Reinitializing an existing record retains its index. The target starts absent, the action selector starts at -1, and the cooldown starts at zero. Move bindings follow COMBAT.INI actor move selection.

Ordinary cell and persistent actor allocation clears the actor record before common initialization. The death selector and object-update exclusion therefore start at zero, and the combat-state association starts absent. These are allocation values, separate from later player-role setup and gameplay changes.

Both standalone player roles use the same cleared object allocator before player-specific initialization. Their collision metadata therefore also starts at zero.

A fresh ordinary actor’s collision metadata byte starts at zero. When its initial model uses the static load path, the loader copies the collision byte from the matching named ROB segment when that segment exists. The MPOB static-model fallback performs the same copy. Loading geometry and retaining this per-actor collision metadata are separate operations; a standalone model resource does not itself supply the ROB byte. Live static face candidates retain the actor’s stored byte as support metadata.

The nonplayer death-animation paths pair a forced request for group 122 with stored death default 124, and a forced request for group 121 with stored death default 123. The requested death animation and the subsequent ordinary default are separate values; the default selector reads the stored combat-state value. Storing the combat death default first releases the actor’s held walk-node reservations. Each node’s ownership byte is cleared only when it matches the actor identifier’s low byte; both actor-side reservation indices are reset.

Forced requests

A forced request for the current group, before its exit marker is set, clears the pending request without restarting the cursor, countdown or finite loop count. Otherwise it clears the current group, replaces the pending group, and resets cursor, direction, delays, markers and finite loop state. A missing group falls back to the existing default, using the same byte speed-modifier addition as an ordinary request. With an accepted group it immediately advances using the existing shared nominal ticks. Ordinary numeric pending priority does not apply to a forced request.

These rules do not make an ineligible actor eligible. The request and advance boundaries reject globally disabled animation, an absent animation state, and actors using the static model shortcut.

Ordinary actor update order

After the actor passes the update-list exclusions, its state-dependent default group is selected. For an actor whose animation-update exclusion is clear, the update then advances the current animation and makes an ordinary request for the selected default. The actor’s main script stage comes later in that same update, after this advancement and the intervening movement handling.

Within the enabled main script stage, the engine processes script entry work, then existing tasks. Task processing can leave the main script body eligible to continue in that update. Actor flags and global script switches can suppress these stages independently; nearby-cell membership does not bypass them.

Consequently, a script animation request can follow an animation advancement in the same actor update. If the request clears the current default or starts an actor with no current group, its immediate advancement reuses the shared tick increment. A renderer that advances each actor exactly once before or after all script execution loses this ordering.

Ordinary collision stage

The ordinary collision branch follows main-script processing and the periodic actor update. In its admitted nonplayer path, a nonzero collision attribute byte 1 runs the support query before the movement and ground response selected by bit 0x04. Body-contact collection and response follow that work. Bit 0x01 enables those contacts only for living actor state zero, state 15, or states 27 through 32 inclusive.

Bit 0x04 dispatches states 10 through 19 to a selected-player-only response handler. For a nonplayer actor that handler returns without changing actor state. Outside that range, states 20 and 21 run weapon-draw admission, including its cleanup branch. They do not also run the ordinary motion and ground response. Other states select that ordinary response. This dispatch does not suppress the preceding support query or subsequent eligible body contacts.

Before support, ordinary nonplayer collision runs the forward obstacle wrapper, except for living states 10 through 19, then the overlap stage when attribute 1 has bit 0x08. Slope prevalidation precedes the primary support query. Ground response selected by bit 0x04 precedes stable-position retention and eligible body response. Conditional recovery and water rollback follow body response. Before recovery the actor’s weight attribute 6 is restored from reserved weight attribute 115.

After collision handling, support-following runs before attribute-controlled axis restoration. These stages can change the result of earlier script movement; updating the animation or local transform alone does not perform them.

Supporting actor motion

The ordinary nonplayer support-following stage uses the retained supporting actor. A missing actor owner or a supporting actor with attribute 24 zero leaves the rider unchanged. Static-placement ownership alone does not carry a rider.

For an unattached support the stage reads its current local position and update-entry local position. The latter is separate from its stable grounded position. A support whose linked-position record names an owner supplies the record’s cached position and its position before the latest refresh instead; angles always come from the support’s own local angles and angle history. It first adds the support’s position delta to the rider’s local position and adds the support’s heading delta to the rider’s local heading, wrapping heading to 2048 units.

It then subtracts the support’s current position from the translated rider. It builds an identity matrix rotated in yaw, pitch, roll order using the negative previous support angles, and applies the column transform to that offset. It builds another matrix with the negative current support angles and applies the row transform. Both transforms store input coordinates as single precision and convert each result to an integer with nearest-even rounding. The final rider position is the resulting offset plus the current support position. Pitch and roll affect position but do not change the rider’s pitch or roll.

An attached support uses current and previous effective positions and angles (each family refresh stores the effective values it replaces as the previous ones); this path does nothing during the first two family generations. Living states 10 through 19 follow the ledge-support actor instead of the retained ground support, with the same attribute 24 and attachment rules. The retained ledge point receives the support’s translation and the same rotation about the support, and the ledge heading receives the support’s heading delta, wrapped to 2048 units, in the same pass as the rider. The selected player in those states is not subject to the destination collision queries below. Otherwise, for the selected player with collision attribute bit 0x01 set, the support’s translation and heading delta are applied first and the candidate models are gathered again at that translated position. The rotated destination is then rejected when the player’s body spheres, placed there with the current angles, meet a candidate (candidate type 0x80 is skipped while queued motion is 24), or when the segment from its update-entry position to the destination meets a candidate. Polygon sidedness is off for both tests. A rejected destination leaves the translated position and the turned heading in place; an accepted one stores the rotated position. These cases are distinct from the ordinary unattached nonplayer path.

Ordinary actor eligibility

The ordinary actor update traverses the actor update list. It skips the actor body for the unselected member of the two designated player actors, a matching active script-name exclusion, a nonzero runtime object-update exclusion, or script-control mask 0x08. This suppresses the ordinary animation stage and later main-script stage together. Update-list membership alone does not make an actor eligible.

The runtime animation-update exclusion is separate. A nonzero value skips the ordinary animation stage, including current-group advancement and its default request, without itself skipping the later main-script stage. Direct animation requests retain their own boundary checks. At each ordinary update, the engine clears this exclusion on the selected player actor and sets it on the other player actor.

SYSTEM.INI’s [debug] disable_slaves sets the object-update exclusion for actors with attr_slave set and attr_master clear. disable_master_slaves sets it for actors with both attributes set. These tests set the runtime exclusion; turning off the option does not clear an already-set exclusion in this update branch.

Timing boundary

The normal world loop calculates the shared FPS-derived timing before sampling gameplay input and building the view-centered actor lists. Ordinary actor traversal follows map-list presentation and the rope and shell systems. It runs before the scene-rendering call. Timing is calculated for the loop, not separately for each actor in that traversal.

Animation consumes the shared whole nominal-tick increment. The normal timing path accumulates eight-fractional-bit frame scales and takes the difference between consecutive whole accumulated values. It can therefore supply zero, one, or several ticks during an update. The first twelve updates after a timing reset use one tick. See player timing.

Selected blocking operations, including model resource loading, rebase the FPS measurement baseline so that suspended time does not enter the next update. The player timing section documents the save, restore, reset, and startup rules.

Shipped FLAG2 sequence

The shipped island FLAG2 program contains finite PushAnimation requests. It requests groups/counts (1, 25), (10, 1), (1, 3), (10, 2) and then ends the invocation with target zero. A later eligible script stage can restart that authored sequence. Replacing it with a single endless idle group loses the group changes and task boundaries. See SOUP End.

Forward frame countdown

For a newly selected group, the command cursor starts at zero and the byte countdown starts at the group’s low header byte plus the request’s speed modifier. With zero input ticks, neither cursor nor countdown advances, but control commands are still interpreted until a frame is selected.

With nonzero input ticks and a zero countdown, the cursor advances one command, the countdown reloads, and the remaining tick count minus one becomes a frame skip count. The countdown then decrements once, with byte wrapping. With a nonzero countdown, it only decrements once and the current frame remains selected. Thus the countdown and multi-tick frame skipping are separate inputs.

Control commands do not consume that frame skip count. Each encountered ShowFrame consumes one skip while a skip remains. The interpreter advances past those frames and selects the next one when no skips remain. It does not interpolate vertex positions between model frames. These rules describe a forward current group; reverse playback, pending-group eligibility, delays, and event dispatch have additional state.

Reverse frame countdown

A reverse-playback byte equal to one changes the ordinary command step to minus one. Frame-countdown expiration decrements the signed command cursor and the wrapping frame-progress byte. Skipped ShowFrame commands decrement both again. A nonzero countdown only decrements once per nonzero-tick update, as in forward playback; zero ticks leave the countdown and cursor unchanged.

Before each reverse command is decoded, a cursor less than one ends the current group. Command zero is therefore not displayed by reverse traversal. Playback clears the current group, stops its remembered sound if present, and invokes ordinary advancement again with the same tick input. With no pending group, that advancement requests the default group.

Delay processing still precedes reverse advancement. An unexpired or indefinite delay yields without decrementing the command cursor. An expired delay clears and lets reverse advancement use the call’s complete tick input.

Reverse control commands

With no finite loop countdown, reverse GoToPrevious and GoToFuture decrement the command cursor rather than taking their targets. A nonzero finite countdown changes this behavior. GoToPrevious decrements it; reaching zero advances the cursor by one, while a remaining count takes the authored target. GoToFuture with a nonzero finite countdown advances the cursor by one without changing the countdown.

Each reverse command iteration clears the exit marker, movement-suppression marker, and retained translation and rotation deltas before testing the cursor boundary. BreakPoint sets movement suppression and steps backward, so the next iteration clears that marker again. Translation, rotation, group-change, loop-marker and native commands step backward without applying their forward operations. Loop-marker commands leave their retained loop counter unchanged.

Reverse DelayCounter stores the narrowed byte delay and decrements the cursor. A nonzero delay yields immediately; zero continues command processing. EndAnimation still ends the group and invokes ordinary advancement. PlaySound dispatches the ordinary animation sound services and retains the returned sound slot before decrementing the cursor. Opcode eleven still invokes the actor-event service with the authored operand and decrements the cursor.

Actor events

Opcode eleven dispatches its operand to the actor-event service at the command, in forward and reverse playback alike, and then moves the cursor one step in the playback direction. The service runs synchronously, in command order with sound commands, and never selects a frame.

The operand is a bit set. The service tests its bits in this order against the actor’s stored sound surface:

A set bit whose surface does not match does nothing, and bits 0x02 and 0x04 together request two effects. Each effect starts at the actor’s current logical Q8 position, displaced 2048 Q8 units toward the camera, with the vertical point logical Y plus the actor’s positive vertical extent times 256 plus 1536. This is the point the landing effect uses, with the camera-relative displacement of the selected death effect admission rules. Bit 0x10 then adds one screen-shake impulse. No other bit has an effect.

Action words

Each actor has a pending action word and an accepted action word. SetAction(mask) accepts only mask 1 or 2. When neither word already contains the requested bit, the call checks that the current group is in 0x41..0x4a and that falling and queued-motion bytes are clear. A failed check clears the two low action bits in both words. A successful request sets the requested low bit in the pending word and starts the action-specific animation request; the pending timer is reset.

The per-tick action update adds the elapsed tick count to the pending timer. After 36 ticks it moves the pending bits into the accepted word and clears the pending word. It clears the low bits when no queued motion is active and the actor is outside groups 0x12 and 0x1e. Accepted bit 1 requests the default action-8 queued motion; accepted bit 2 requests default action 9. Those requests are admitted only when the actor is not already queued, falling or sliding and has living state 0 or 15; the selected player also requires the normal non-water admission.

ResetAction(mask) clears the requested bits in both action words. ResetAllAction clears the pending word and copies the cleared value to the accepted word. The words are actor state and are independent of the selected player’s controller pending-action flag.

Transition command

Opcode fifteen carries a trigger mask, a start frame and a target group. Reverse playback only moves the cursor one command back. Forward playback asks a decision routine, keyed on the mask, whether to take the transition:

A command that is not taken advances the cursor by one. A missing actor or animation record is never taken either.

Taking mask 8 sets byte +0x0a of the animation record to one, then makes a group request on the actor through the shared group-force routine: group 31 for a selected player holding a weapon, otherwise group 30 with a burning torch or group 18 without one. Each path sets bits 0x30 of the actor’s combat-state byte +0x1cc and runs one further update routine for the actor before the decision reports success. Masks 1 and 2 report a distinct success value from mask 8 and mask 4.

The decision result selects the command’s outcome. Not taken advances the cursor by one. A mask 8 transition leaves the cursor on the command and ends the update with the group request already made. A mask 1 or 2 transition sets the cursor to the command’s second operand less two (the start frame field) and, like a taken GoToFuture, sets the exit marker and clears the two six-byte delta records. A mask 4 transition does the same with the third operand, as described next.

Taking mask 4 jumps the cursor to the command’s third operand (target_group, a command index below 128) and continues interpreting there, exactly as a taken GoToFuture does: it sets the exit marker, clears the movement-suppression marker and clears the two six-byte delta records. The decision for mask 4 has no other effect.

Forward type-one transitions

A forward type-one group uses the ordinary frame countdown and control commands. With no finite loop countdown, a pending group different from the current group makes GoToFuture take its exit target. The jump sets the exit marker and clears the movement-suppression marker before interpreting the target commands.

A pending default does not immediately replace a type-one group, even after the exit marker is set. Playback continues through the exit tail until EndAnimation, which selects the pending default in the same advancement with the same nominal ticks. With a pending non-default group, an already-set exit marker instead permits replacement at the beginning of a subsequent advance, before its ordinary countdown update. The pending group number may equal the current number. The ordinary request priority rules still determine which request becomes pending.

Delay processing precedes that replacement test. An unexpired finite delay or an indefinite delay yields before replacement eligibility is checked. When a finite delay expires, replacement receives the call’s complete tick input. Selecting the replacement resets its cursor, countdown, loop state and markers.

Zero-tick updates retain the currently selected frame. The walk group’s PlaySound command in the exit tail does not end the group or consume a frame skip. See animation sound requests.

Forward type-two groups

A forward type-two group (ledge-hang loops, and the player’s and pirates’ idle and movement groups) uses the same exit-marker replacement rule as type one: once the exit marker is set, a pending group that exists and differs from the actor’s default group replaces the current group at the start of the next advancement.

GoToFuture differs. With no finite loop countdown and either the exit marker set or a pending group differing from the current one, a type-two group whose pending group is the actor’s default group does not take the exit target: the cursor advances by one command, the exit marker is not set, and playback continues past the jump. Any other pending group takes the exit target as in type one.

Forward animation delays

DelayCounter, opcode twelve, narrows its operand to a byte, advances the command cursor, and yields without selecting a new model frame when that byte is nonzero. Zero continues interpreting commands in the same invocation. The previous displayed pose remains selected during the wait.

At the start of subsequent advancements, byte value 255 yields indefinitely. For another nonzero value, the engine subtracts the shared whole nominal ticks with wrapping 32-bit arithmetic and tests the signed result. A positive result is narrowed back to the delay byte and yields. Otherwise the delay clears and ordinary advancement continues in that same call, using the original tick input in full. The delay does not consume a portion of the frame-skip input. A zero-tick advancement therefore preserves a finite delay.

Waiting neither ends the current group nor completes a task waiting for a group change. Selecting a replacement group clears its delay state. The cursor has already moved past the delay command; the usual countdown and frame-skip rules still apply when the delay expires. ConditionalDelay and LoopControl use separate state from DelayCounter.

Breakpoints and walking translation

BreakPoint, opcode five, sets a marker in the current animation state and continues interpreting commands. It does not pause the game or the animation. Ordinary forward walking checks this marker after advancing its startup phase; a set marker suppresses that update’s translation. Queued and falling vertical writers read the same marker after their preceding animation request. A set marker suppresses their vertical arithmetic and timer updates. Static models and absent animation state do not apply this suppression.

For forward playback, advancing the command cursor when its frame countdown expires clears the marker. Skipping a ShowFrame, taking a GoToPrevious backward jump, or taking a GoToFuture exit jump also clears it. A zero-tick update or a countdown decrement that keeps the same cursor does not clear it. A later BreakPoint can set it again before the selected frame is returned. Selecting a new group resets the marker before interpreting its commands.

Ordinary collision rollback snapshot

After ordinary animation advancement, the update saves the current animation receiver and the two selected model-frame words, together with the directional movement flags. Late collision rollback restores those saved values. The receiver snapshot includes the current group, pending request, command cursor, countdowns, loop state, exit and motion markers, and remembered animation sample slot. The separately stored default animation selection is not restored.

Restoring a remembered sample slot does not stop channels started after the snapshot or restart a channel that has already stopped. A later animation stop uses the restored reusable slot, including a replacement sound occupying it.

Animation group classes

The engine keeps a table of one class value per animation group number (0 through 177), consulted by combat and movement code to decide whether a group is a fighting group or a reaction group. Groups not listed have class zero.

Player movement

Player movement combines held input, actor attributes, animation state, and a shared frame scale.

Coordinate and heading units

Runtime positions have eight fractional bits. A marker coordinate of 40816 becomes a runtime coordinate of 10448896. The developer console’s object coord command displays both representations. Its start position retains the spawn position while the current position changes with movement and ground contact.

Headings wrap after 2048 units per revolution. For ordinary ground movement with the sword sheathed, forward at heading zero increases Z. Right turning decreases heading; left turning increases it. Combat and special movement states use different rules.

Marker-based world entry

A marker-based world load selects the requested map marker and uses its position for the initial player position. The marker coordinates are multiplied by 256 for runtime storage. The requested heading is wrapped modulo 2048; the marker’s auxiliary byte does not supply a heading. The player actor uses the map’s CYRUS actor definition, including its attributes and animation data.

The two standalone player actors use the shared actor allocator. Their motion state, rope attachment, torch-burning counter and weapon-drawn flag start at zero. Model and animation setup are separate from this allocation state.

Initial placement and ground settling are separate. Ground settling can change the player’s Y coordinate, so the marker’s Y coordinate is not a permanent ground height.

Startup ground settling

Startup ground settling is separate from the ordinary grounded movement update. It prepares the spatial window around the actor X/Z, using the static collision list order. It queries nearby model candidates with radius 1000 map units, excluding the actor’s current model. The candidate list is the one the ordinary collision queries build, so it holds more than the static placements: after them come the models of the ordinary actors that have a model, are not the excluded player role, are not excluded from object updates, have attribute 55 equal to zero and pass the model-distance test, and only an actor whose model kind byte is one contributes to the face-model list the contacts are taken from. An actor-owned deck, such as a ship, therefore competes with the terrain. The vertical segment keeps the prepared actor X/Z and extends 500 map units in each direction from the prepared actor Y plus its positive Y extent.

When terrain is enabled, its sampled height is truncated toward zero to an integer map height. The terrain query does not test water cells: a water cell supplies the same interpolated height as a dry cell. Terrain is eligible only strictly between the segment endpoints. Its rank is abs(16384 - ((abs(height - start_y) * 8388) >> 8)). The initial rank without eligible terrain is 65536.

Model contacts are visited in candidate and contact order. Only surface classifications 2 and 4 participate. Their rank is abs(16384 - contact_rank). A model contact replaces the current selection only when its rank is strictly smaller. Equal ranks retain the earlier selection, including terrain when it was selected first. This differs from ordinary support selection’s later-equal replacement.

If a support is selected, the actor Y becomes (selected_height - positive_y_extent + standing_height) * 256, where standing_height is the configured map-unit value from SYSTEM.INI. Without a selection, the actor Y is unchanged. This pass does not translate X/Z.

Ordinary idle animation default

For the ordinary grounded player at rest with the weapon sheathed and no special action override, default animation selection reads attr_panic_group from the actor’s attributes. This is a group number, not a boolean or a hardcoded request for group zero. The installed ISLAND CYRUS definition supplies zero.

This selection precedes the ordinary animation advancement and default request. Combat, rope and special-action states use separate selection branches.

Upright actor orientation

Actor orientation stores pitch, heading and roll modulo 2048. Assigning an orientation rebuilds the actor matrix from identity, applying negative heading, negative pitch and negative roll in that order. The rotations use the floating point shared rotation table.

For zero pitch and roll, let s be the table sample at negative heading modulo 2048, and c the sample 512 entries later. The matrix rows are (c, 0, s), (0, 1, 0) and (-s, 0, c). It maps local forward onto (s, 0, c) in original world axes. Use the stored table samples even at quarter and half turns; replacing their small residual values with exact mathematical zeros changes integer collision conversion at some distances.

Incremental orientation refresh

Assigning an orientation and refreshing an existing actor matrix are distinct operations. In the ordinary unattached refresh branch, changed angles with attr_rotation = 0 rotate the existing matrix by the negated differences between current and previous heading, pitch and roll, in that order. Each difference is wrapped modulo 2048 for the shared rotation-table lookup. Unchanged angles leave the matrix intact. The stored matrix therefore retains its accumulated single-precision rotation history; it is not reconstructed from the current heading on every refresh. The ordinary actor update copies current pitch, heading and roll into their previous-angle fields before selecting the default animation and running the ordinary animation block. Movement later in that update can change the current angles. The admitted incremental refresh does not advance this snapshot. In the normal main-loop order, map-list presentation, which can refresh actor matrices, precedes the ordinary actor update. Explicit orientation assignment and attached-actor composition remain separate operations.

In that branch, attr_rotation = 2 instead rebuilds from identity using the negated current angles. A selected player with nonzero roll takes a separate rebuild branch. These rules do not replace attached-actor matrix composition.

Ground-turn arithmetic

Left and right input have independent turn accumulators. Releasing one direction resets its accumulator to zero. For ordinary movement, a held direction adds SYSTEM.INI turn_speed while its accumulator is below turn_max_speed. The addition is not clamped, so settings whose increment does not divide the limit can overshoot it. The installed values 12 and 48 produce held-input accumulators 12, 24, 36, 48, 48 on consecutive input updates.

Each direction is multiplied by the current frame scale and shifted right by eight bits separately. Ordinary ground turning adds the scaled left amount and subtracts the scaled right amount, then wraps the heading modulo 2048. At scale 256, starting from heading zero, five right-input updates produce headings 2036, 2012, 1976, 1928, 1880. These are arithmetic examples, not a claim that input updates occur at a fixed wall-clock frequency.

Animation and player state control whether this heading update is allowed. The arithmetic alone is insufficient to implement the player state machine. Each input update recomputes both accumulators. A direction that is not held resets to zero; with no selected player a held direction is one. Otherwise the accumulator is incremented by the ordinary settings, or by the selected player’s fight-turn attributes when either of these holds:

• The player holds a weapon (attribute 110 is nonzero, or the item system is ready and the player has an assigned, drawn, not sheathing weapon) and its current animation group is neither 18 nor 31.
• Its hand_item is 51.

The fight-turn increment is attr_fight_turn_accel (attribute 22) and the limit is attr_fight_turn_speed (attribute 21): while the accumulator is below the limit the increment is added, with the same overshoot as the ordinary settings. CYRUS carries accel 12 and speed 64, against the ordinary 12 and 48; the attr_turn_speed attribute (15, value 32) is not read by this update.

Ground-turn eligibility and animation

Keyboard turning runs inside the selected player’s controller, after the view, lockout, dialogue and topic-menu returns and before forward and backward dispatch, so movement in the same update uses the turned heading. The controller also returns before turning while the current animation group is 129 or 91 and the item system is ready and not paused. The rules below cover a sheathed, non-swimming player that holds no item. While the player holds item 51 the accumulators use the fight-turn attributes, the ordinary turn animation is suppressed and the keyboard movement dispatch after turning is skipped.

Without the walk key held, turning applies when the living state is 0 or 27 and the actor’s motion bytes at +0x1b2 and +0x1b3 (two of the sliding, falling and queued-motion bytes) are both zero. The heading becomes the previous heading minus the scaled right amount plus the scaled left amount, modulo 2048. A nonzero net amount then makes an ordinary animation request with modifier zero:

No request is made while the actor is a swimmer (attribute 110 nonzero), holds a drawn weapon with a combat record, or stands on surface 2 or 4. Equal left and right amounts request nothing.

With the walk key held, turning applies only while forward or backward is held, the motion bytes at +0x1b2 and +0x1b3 are zero and the living state is outside 10 through 19. It requests no animation and does not bank.

These rules hold with the installed [cyrus] mouse_turn=0. A nonzero value adds a mouse-driven turn block that plays the same four turn groups from the sign of the horizontal mouse movement.

After turning and before forward and backward dispatch, a sidestep block runs when the walk key is held or the living state is 15. With neither forward nor backward held, left alone calls MoveLeft and right alone calls MoveRight with duration 1, using the same stepper as the script natives; the controller ignores their result. Holding forward or backward skips the sidestep.

The third actor angle is a roll that banks while running. It changes only in these rules, all modulo 2048:

• When the current group is 18 or 30 and turning applies without the walk key, a left turn adds 4 (8 while roll exceeds 1024) when roll is below 32 or above 1024; a right turn subtracts 4 (8 while roll is below 1024) when roll is above 2016 or below 1024. Other rolls are unchanged. With no net turn the roll relaxes.
• When the current group is neither 18 nor 30, the roll relaxes once per update, and twice when turning applies without the walk key and the net turn is zero.
• Relaxing: above 1024 the roll becomes 0 when it exceeds 2040 and otherwise gains 8; from 1 through 1024 it becomes 0 below 8 and otherwise loses 8; zero stays zero.
• Any other update in groups 18 and 30 leaves the roll unchanged.

Movement data and timing

Forward running and walking use the actor’s attr_forward_speed and attr_forward_walk. They are actor data, not universal controller constants. Startup movement also depends on attr_step_type and animation progress.

The frame scale uses eight fractional bits, with 256 representing one nominal update. The first twelve updates after a timing reset use 256. Subsequent timing can use an FPS-derived scale with the configured normal, minimum and maximum frame rates and smoothing settings. A nominal frame rate of 12 does not mean the game runs a fixed 12 Hz simulation.

Heading-based translation

Horizontal translation uses the floating-point shared rotation table, not the separate integer sine table. Negate the actor heading and mask it to 2047 to select the sine sample; cosine uses the sample 512 entries later. Multiply the integer movement distance by each sample and add it to the current X or Z position converted to single precision. Store the sum at single precision, then truncate it to the runtime integer coordinate. Rounding the sum before integer conversion is observable at ordinary world coordinates.

For heading 2036, distance 680, and initial X/Z (10446802, 10818615), the result is (10446827, 10819295). Keeping the sum at double precision until truncation would give a different Z result.

Direction recovered from displacement

Collision response derives a movement heading from the integer X/Z displacement. Take the absolute components and repeatedly halve both, discarding remainders, until neither exceeds 511. Axis-aligned vectors select the corresponding quarter revolution directly. For two nonzero components, equal magnitudes select 256; otherwise index a first-octant table with floor(512 × smaller_component / larger_component). When X is larger, subtract the table result from 512. Reflect this first-quadrant angle according to the original component signs, negate it for the actor-heading convention, and mask to 2047.

The 512 used first-octant entries are truncate(atan(index / 512) × 65536 / 3.141592654) >> 6. The diagonal case uses its explicit value rather than indexing an extra endpoint. Directly rounding a continuous atan2 angle produces different results.

Ordinary controller dispatch

The selected player’s native controller runs within the ordinary script stage. Default selection, ordinary animation advancement, and the ordinary default request precede that stage. Queued and falling motion also precede the script stage. Animation-based movement continuation and ground response follow it. Returning from the controller does not skip those later ordinary stages.

A freshly loaded executable initializes the retained LockoutPlayer word to zero. Any nonzero retained word returns from the controller before keyboard movement dispatch. After that check, either the dialogue-state word or the topic-menu-state word being exactly one also returns before movement dispatch. These controller tests are separate from the attribute assignment performed by LockoutPlayer.

The controller combat predicate is false when the actor has no combat record. With a combat record, it is true exactly when combat flags mask 0x04 is set. This is the same flag set by beginCombat, rather than a separate controller assist field. Combat-record allocation and reinitialization explicitly clear the flags byte before the remaining combat setup.

For an ordinary grounded player with the sword sheathed, combat flag 0x04 clear or no combat record, no rope attachment, and no jump or view input, the held walk/run key inverts the retained walk-mode choice:

Walk mode comes from [CYRUS] WALK_MODE in SYSTEM.INI; Tab toggles it. Forward input takes priority over backward input when both are held. With no forward input, backward input takes its separate dispatch branch. The view key returns before this ordinary non-combat movement dispatch.

The run helper is the script native MoveForward and the walk helper is WalkForward, each called with duration 1 and an ignored result. Both use the shared step counter, animation request and translation-suppression rules of MoveForward and WalkForward.

With no forward input and backward input held, the same walk rule selects WalkBackward or MoveBackward, each called with duration 1: the walk helper when the walk mode and the held walk/run key differ and the run helper otherwise. In a lifecycle state of 0x14, 0x15, 0x21 or 0x22 forward and backward dispatch is unchanged, while left and right turning does not run.

A player that holds a weapon (the weapon-holding predicate) or has combat flag 0x04 set ignores the retained walk mode in both forward and backward dispatch: the held walk/run key alone selects the walk helper, and its absence the run helper. Without the walk/run key, a held jump key starts the jump entry in place of the helper for a player that holds a weapon only while the action key is not held, and for any other player only while the current group is not a running group (forward) or one of the walking groups 19 and 23 (backward).

The helper selection does not bypass the helper’s motion, support, animation, or movement-marker tests. Water states, drawn weapons, rope motion, jumping, and special living states have separate dispatch branches.

Armed attack input

The input sampler keeps a tap latch per key (up, left, right, the walk key, jump, look and action). Once per world-loop iteration a latch whose key is not held counts frames since release and clears its press count when that timer exceeds the tap window; a latch whose key is held and was not held the previous iteration counts a press: the count rises when the release timer is above zero and below the window, and restarts at zero otherwise, and the timer restarts either way. The window is [cyrus] tap_time shifted left eight bits and divided by the frame scale (signed), with a floor of six. A latch query names a key, a count and whether to consume: it matches when the press count equals the count, and a consuming match clears count, timer and held flag.

After movement dispatch, and only while the jump key is not held, a player holding a weapon runs the action-key handler. It does nothing in lifecycle states 20 and 21, without a combat record, without the action key, or unless the combat action selector is -1, 0 or 1. While the queued byte is nonzero or the falling byte is one, it records a pending jump attack, which starts the jump attack once falling is one; otherwise the record clears. With the first directional-state byte’s low two bits set it only consumes the action latch. Otherwise it selects one move:

With none of these the action latch is consumed. A move starts only when its authored attack slot is populated and the pending move word allows it: moves 0 and 3 need it to be -1, move 1 needs 0 and move 2 needs 1. Starting writes the move to the action selector and the pending move word and runs the executor with request 0: the move number selects the attack slot, the executor starts that slot’s first motion (animation group, motion selector zero), sets combat intent bit one, sets the attack state to one and lowers aggression by ten. A hit on a target then follows the ordinary attack-processing rules for the current slot and motion. The jump attack is move 6 started once the falling byte is one: it needs its authored slot and an empty pending word, and consumes the action latch.

The lunge (move 4) first moves the player: when its lifecycle byte is zero and no rope, sliding, falling or queued motion is set, it takes one MoveForward step of attribute byte 16 (whole units times 256) along the local Y heading, with the same forward step check below startup counter three, the same startup ramp and frame scaling, but no animation request. The move also needs its authored slot, a zero cooldown and no drawing or sheathing state before this step is taken. Before any of these moves (0 to 4 and 6) starts, a reach test runs over the ordinary actor list, with the move number selecting the attack slot and the slot’s first motion supplying arc, arc_center, min_range and max_range. An actor is in reach when its distance from the player (the rounded three-dimensional distance between query positions) is strictly between min_range and max_range and the absolute wrapped difference between the player’s heading and the heading toward the actor is strictly within arc_center + 512 plus or minus arc. The receiver itself is not excluded from the list. The start proceeds when either:

• an actor with a combat record is in reach and is either attackable (attribute 97 zero) or in lifecycle selector 6; or
• no actor is protected: a protected actor is in reach, is not in lifecycle selector 6 or 8 and has attribute 97 nonzero. For the forward move (3) the arc half-width used for this protected-actor test is six times arc, evaluated in single precision.

Otherwise the move does not start and the player requests an opponent-unarmed taunt: type 11 when the protected actor’s attribute 118 is nonzero, else type 10. Those taunt types use ordered selection like begin-combat taunts, and are not requested while the retained taunt cache entry still remembers a sample.

Armed look-key handling

The look key leaves the movement dispatch, but the armed handler described above still runs, ahead of the attack keys and only while the jump key is not held. In order:

1. With both the look and action keys held, a timer adds the nominal ticks of the iteration. Once it is greater than [cyrus] sheath_sword_delay (6 when the configured value is zero) the handler runs SheathSword for the player. The iteration ends either way. Any other state of the two keys clears the timer.
2. A drawing or sheathing sword ends the iteration.
3. With the action key held the attack selection above follows.
4. With the action key released, a counter that adds the nominal ticks of every iteration is compared with COMBAT.INI [misc] cyrus_defend_interval. When the look key is held and the counter is greater, the defence stance starts (below) with [cyrus] auto_defend off, or only when an automatic defence is found with it on. A started stance sets the low two bits of the combat flags to 2 and clears the counter.
5. A jump attack still pending while the falling byte is one then starts as in the attack selection, and the action latch is consumed.

The defence stance does nothing unless no move is selected. It sets the pending defence index to zero, or to the counter-attack reference of the first attacker when that attacker is in the player’s forward arc (strictly under 256 heading units) and its attack state is one. An attacker is an actor in the ordinary list other than the player with a combat record whose target is the player, whose attacker-selection state is one and that is not dead. The stance then selects move nine and runs the defence executor, which requests the selected defence’s animation group, sets attack state two and lowers aggression by ten.

The automatic defence visits the attackers in list order. An attacker qualifies when it is in the forward arc, has combat flag 0x01 and attack state one, and the strike window of its current motion lies inside the active window of the player’s defence record for that motion’s counter-attack reference. With gap_near = first_collide_frame - cursor and gap_far = first_defend_frame - cursor (the cursor is the attacker’s animation command cursor) and the defence’s first_collide_frame as start and first_collide_frame + collide_duration as end, the window is inside when start < gap_far or gap_far <= 0, and end > gap_far, and start < gap_near, and end > gap_near. The first qualifying attacker starts the stance.

Controller initialization and preliminary state

Creating the standalone CYRUS and GREMLIN actors runs the same player initializer for each actor, then restores CYRUS as the selected player. Each initializer clears selected hit inhibition, the death-animation override group, the pending action flag, three preliminary countdowns and sound-maintenance inhibition. These resets precede actor model/script setup and the initial animation request.

The preliminary countdowns are unsigned 32-bit values in whole nominal-tick units. One countdown advances only while both queued-motion and falling states are zero. The other two advance on every controller call. Each nonzero countdown subtracts the nominal-tick increment with saturation at zero. These three countdowns are separate from the selected-player support-history counter, which advances earlier in the ordinary actor update.

The conditional countdown is processed before the pending action flag. A pending action with sliding state zero selects action 74 and invokes its action helper: it stores group 74 as the death-animation override and applies health -255 through the death-owning selected-player health, naming the player as the source. The flag is not cleared by the helper, so each controller call with sliding state zero repeats it. The two unconditional countdowns are processed afterward, before the selected hit-inhibition test. Nonzero hit inhibition invokes the death controller and returns before idle-counter reset, lockout and ordinary keyboard dispatch.

Idle animation requests

The ordinary idle counter starts at zero in a freshly loaded executable. The controller resets it to zero while attached to a rope or while the current animation group is nonzero. This reset precedes the lockout test. With the normal BIOS clock, the clock measurement advances the counter once per accumulated 18 BIOS timer ticks, independently of the nominal animation tick increment.

After the lockout check, an unattached player with attr_health < 40 requests group 4 when the signed idle counter is greater than 4. At health 40 or above, a counter greater than 12 requests one of groups 1, 2, or 3. Selection draws the shared random generator’s low two bits, retries value 3, and adds one to the accepted value. Either request first sets the idle counter to -1.

These requests precede the dialogue and topic-menu checks. They use the normal animation request operation and do not replace the actor’s default group.

Controller under queued, falling and sliding motion

The selected player’s controller reads the queued, falling and sliding bytes in only the places below; all other branches ignore them. The rows assume living state 0, no rope attachment and a sheathed sword. Rope attachment, living states other than 0 and a held weapon take separate branches.

Living state 0 is not required for the preliminary rows. Banking is not touched when the turning block is skipped, but the single post-block roll relaxation still runs.

With the forward key held, a queued byte whose low seven bits equal 1 and a current group of 32 or 33 becomes exactly 2, clearing its high bit. This runs after movement dispatch in the same update, also when the player holds item 51, and has no weapon or walk-key test. Queued state 2 then selects the arbitration animations of queued motion arbitration. Other directional input does not alter queued or falling motion in the controller.

Forward-walking startup

Before startup acceleration, an ordinary forward walk requests its selected walking animation. With [system] animation_system = 1 in SYSTEM.INI, if that request leaves a different group current, the walk returns before marking forward movement accepted, advancing the startup phase, or translating the actor. A pending walking group therefore does not by itself permit movement. The walk movement classification is 6. It is assigned after successful forward-support admission and before the walking-group lookup and request gate. The shared forward-update indicator is set only after the animation request passes that gate. Ordinary forward running uses movement classification 2.

These classifications are distinct from the direction and packed movement flags assigned by directional ordinary displacement. Both classifications select forward direction 2 and movement mask 0x30 in that later stage; the forward-walk helper does not itself assign that mask.

This differs from the animation movement marker gate below, which suppresses translation after startup has advanced.

Ordinary forward walking keeps a startup phase from zero through three. The selected walking speed is converted to runtime position units by multiplying it by 256. For attr_step_type = 1, phases zero, one, and two use one quarter, one third, and one half of that speed respectively, with integer division. Phase three uses the full speed. A walking speed of 8 therefore gives startup amounts 512, 682, 1024, and then 2048.

When the selected walking-speed attribute is zero, the forward-walk helper instead uses attr_forward_speed >> 1 as its runtime-unit startup amount. This fallback is not multiplied by 256. Startup division and frame scaling still apply to that amount.

For ordinary sheathed, non-combat forward walking, the helper selects animation group 20. It checks that the group exists before requesting it or advancing startup. The ordinary request precedes the movement-marker test, so a request that advances animation immediately can change whether this walk translates.

An eligible walking update advances the startup phase before testing whether the current animation permits translation. Suppressed translation does not undo that phase advance. Consequently the first visible displacement need not use phase zero. Resetting the phase whenever translation is suppressed changes the startup behavior.

When animation permits translation, the startup amount is multiplied by the frame scale and shifted right by eight bits before heading-based displacement. Walking groups can use animation type 1; a player animation adapter restricted to type 0 cannot reproduce ordinary walking.

Ending a walking update

The actor update tracks whether it accepted forward movement. At the end of an update without accepted forward movement, it resets the forward startup phase to zero. This differs from suppressing translation through animation: an accepted walking update can advance startup while producing no displacement.

Continuation after input release

Accepted movement is not equivalent to a held input. The actor update can continue movement from its current animation group after the input has cleared. The run-group continuation still passes through the animation marker gate and counts as accepted forward movement when that marker suppresses translation.

For an admitted ordinary sheathed actor whose current group is 20, the update continues forward walking if earlier movement in that update did not already accept forward motion. This continuation repeats the forward support probe and uses the walking speed, startup phase, frame scale, and movement marker. It does not request the walking animation again, so the pending default-group request survives. Marker-suppressed continuation still counts as accepted forward motion and preserves the startup phase. Once the current group becomes idle, this walking continuation no longer applies; an update without other accepted forward motion resets the phase.

For ordinary type-1 walking, a pending default-group request does not immediately replace the current group. A GoToFuture command takes its exit target when a different pending group exists, or when exit processing is already active. The taken jump marks exit processing active and clears the movement marker; a BreakPoint at the target can set the marker again. A pending default remains pending through these exit frames until EndAnimation starts it in the same advancement call, using that call’s tick input.

Ordinary forward-walk support checks

Before an ordinary ground walk is accepted, the engine probes ahead of the actor. The local forward probe distance is the actor’s forward extent plus attr_forward_walk, converted to runtime position units. Actor orientation transforms the offset; the probe retains the actor’s current Y coordinate.

The local offset has zero X and Y components. Its Z component is the sum of forward extent and attr_forward_walk, multiplied by 256. The integer matrix transform converts its input components to single precision, computes each rotated component, and stores that component as single precision before converting it back to an integer with nearest-even rounding. The transformed integer X and Z offsets are added to the actor’s runtime X and Z coordinates; the transformed Y offset is discarded.

The probe must pass three checks, in order:

1. The actor’s collision spheres at the probe must not intersect nearby model faces.
2. The surface check must not reject the probe as a steep surface.
3. A ground-support query at the probe must succeed.

The body check builds the actor’s working sphere shape at the proposed position. Each Q8 position component is shifted right by eight before conversion to single precision; the collision orientation remains the actor’s current orientation. Prepared model candidates are visited in their retained order. Queued motion 24 excludes candidates of type 128. The first blocking model rejects the attempt without querying later models. Terrain does not participate in this body check, and the actor’s stored position is unchanged.

The ground-support query temporarily uses the probe position and then restores the actor’s position. It considers terrain and nearby model faces. This is not a permanent Y clamp and is not equivalent to accepting every horizontal step.

Surface classification uses the signed Y component of a normal scaled by 256:

Ground selection accepts classifications 2 and 4; the separate slope rules control whether movement onto that support is allowed. Surface classification alone does not describe slope sliding or collision response.

An unsuccessful sphere, steep-surface, or ground-support probe marks the forward attempt blocked and returns failure. Subsequent checks in that probe are skipped. The blocked-attempt marker is transient; it is not a permanent collision state.

Forward slope surface selection

The forward steep-surface check uses post_collide_height as the half-length of its vertical segment, centered on integer actor Y plus the positive Y extent. It is bypassed when collision attribute bit 2 is clear, or when the designated player’s support-history counter is nonzero.

For the proposed position, face-model contacts of classification 2 or 4 compete by abs(16384 - segment_rank). Strictly smaller values replace the current contact, preserving the first equal candidate. The initial comparison value is 999999 and the initial model height is 9999999 map units.

Terrain participates when its height is no lower than the segment’s lower end. Its height difference from the segment center is truncated toward zero before taking the absolute value. That value must be strictly less than the absolute difference of the current model height from that center. A winning terrain sample replaces the normal and height. When the proposed position has a selected surface, classification 2 rejects the attempt and other classifications allow this slope check. This selection is separate from the ordinary ground-support rank comparison.

Queued and falling vertical motion

Queued and falling vertical motion skip their arithmetic when an animated model has active model-controlled vertical motion. Static models, absent animation state and animations without that control use the following rules. All positions and the retained fall origin have eight fractional bits. The retained timer is a byte; falling tests it as signed.

The vertical factor sequence at indices 0 through 29 is exactly represented by integer division of 256 * (900 - (29 - index)^2) by 900. Indices 30 through 69 have factor 256. The next entries belong to adjacent engine state. A queued update reads the entry at its current timer before advancing, then reads the entry at the advanced timer to decide whether it transfers to falling. A falling update uses entry zero when the signed timer is nonpositive.

The additional increment is a constant zero: nothing ever writes it. The fine-tick increment is the finer counter increment of the update. While an animated-model actor’s falling byte is nonzero, the ordinary support query instead uses a reduced probe distance chosen by the measured FPS that the frame scale was derived from (twelve during the startup countdown): at 10 or more it is (post_collide_height >> 2) * 3, below 10 it is post_collide_height. Every other ordinary support query, including every static-model one, uses post_collide_height.

Queued motion writes origin_Y - attribute_32 * factor[timer], then advances the timer by the sum of the fine-tick increment and its additional increment, wrapping as a byte. After that advance, a factor greater than 255 transfers the queued byte to falling and clears queued motion. A transferred high-bit motion forces animation group 58 when the torch-burning counter is zero.

Falling limits its vertical value by post_collide_height * 512 - 256, with signed comparison. With a positive signed timer, it writes origin Y plus the smaller of that limit and -attribute_32 * factor[timer], then subtracts the same fine-tick increment sum from the byte timer. With a nonpositive timer, it adds the smaller of that limit and attribute_32 * factor[0] * (fine_tick_increment + additional_increment + 2) to current Y. Products and position arithmetic retain 32-bit wrapping.

The queued-motion clearance probe runs from the current effective integer Y to that Y plus the positive Y extent, retaining X and Z. It visits the prepared face candidates without the queued-motion type exclusion. Contacts of normal classification 2 or 4 compete by their integer world Y; strictly smaller Y replaces the current height, initialized to 999999. With no selected height, clearance is 256000 Q8 units. A selected height returns height * 256 - current_effective_Q8_Y. The terrain query uses current integer map X/Z and truncates its interpolated height toward zero. That height replaces the model result only when it is strictly greater than current integer map Y and strictly less than the retained model height. It does not use the ordinary support-segment rank or lower end. The terrain query runs whenever the world has terrain. It does not test water cells: a water cell supplies the same interpolated height as a dry cell. The probe applies no height-grid bounds check of its own: the height array is addressed linearly (row index times the grid width plus column), so a column past the east or west edge continues into the adjacent row of the array, and the cell interpolation then runs between the last column of one row and the first columns of the next.

Directional ordinary displacement

Directional displacement masks the input motion byte with 127. Values 2, 6, 8, 9 and 24 select forward direction 2 at the actor heading and mark movement bits 0x30. Values 3 and 7 select backward direction 3 at heading plus 1024 and mark 0xc0. Value 4 selects direction 4 at heading plus 512 and marks 0x03; value 5 selects direction 5 at heading minus 512 and marks 0x0c. Other values return without these writes. Selected headings wrap to 2048.

The selected direction and movement bits are written even when the current animation suppresses displacement. Otherwise, stored surface state 2 or 4 halves the signed distance by arithmetic right shift. A positive resulting distance translates local X/Z using the heading-based translation rule. The corresponding directional update indicator is also set.

For an initial ordinary animated fall, current groups 41, 42 and 43 apply this displacement using the retained motion direction and Q8 distance 4096 before selecting their initial fall animation.

Pre-script queued and falling stage

Every actor update runs one stage between the ordinary animation stages and the script stage. Its only content is directional displacement. It has no test for actor kind, selected player, living state or collision attribute mask, so the selected player and every nonplayer take it alike. After the action-transition counter bookkeeping, a nonzero queued byte supplies the motion value; otherwise a nonzero falling byte does. Neither nonzero skips the stage. The sliding byte never selects it. Directional displacement returns without effect while the actor is attached to a rope.

For queued or falling motion 8 or 9 the displacement is forward at the actor heading. It sets motion direction 2, the forward update indicator and movement bits 0x30, even when the current animation suppresses displacement. Otherwise, while the accumulated sliding distance is below 0x18000, each update adds (0x10000 / attribute 31) * frame_scale >> 8, limited so the accumulated distance does not exceed 0x18000, to that distance and translates by the same amount; at or above the cap nothing moves. Motion 2 (a jump steered forward) does the same with 0xb400 and a cap of 0x10000. Deep water halves neither. Other motion values add no displacement here. A zero attribute 31 divides by zero in the original.

Queued arbitration, the queued and falling vertical writers, the edge service, landing and fall start are not part of this stage. They run only inside the ground response, which an animated actor reaches only when its collision attribute mask has bit 4 set. An actor whose ground response does not run therefore still receives this displacement every update while its queued or falling byte is nonzero, and never advances vertically, lands or starts a fall.

Ground stage by model kind

A static-model actor runs its ground stage only when attribute 108 is nonzero and attribute 107 is zero, regardless of the collision attribute mask: the support query, then the ground response. The animated-model ground stage is selected by the collision attribute mask instead: a nonzero mask runs the obstacle pass unless the selected player is in its alternate collision mode, mask bit 8 runs the overlap pass, the support query follows, and mask bit 4 runs the ground response. Attribute 107 nonzero also ends a fall at the first support miss: the falling byte is cleared and nothing else changes.

Ordinary landing decision

On support regained while falling, clear the runtime jump selector and compare the absolute wrapping difference between current local Q8 Y and retained fall origin. Resolve and store the landing surface before this comparison; surfaces 1 through 4 replace the compared distance with zero.

The death threshold is SYSTEM.INI [game] fall_death_height * 256, and the hurt threshold is fall_hurt_height * 256, retaining 32-bit arithmetic. Distance strictly above the death threshold requests fatal landing and applies health change -256. Otherwise distance strictly above the hurt threshold requests group 73 and applies -fall_hurt_zap, except when the actor’s separate hurt-exclusion predicate suppresses both. That predicate is true for stored surface states 1 through 5 and 11. These threshold branches precede the ordinary landing animation selection. They clear the falling byte.

For the ordinary nonplayer fatal path, group 74 is an ordinary request. The ordinary hurt group 73 also uses ordinary request arbitration.

The selected player takes the same threshold tests and the same hurt response: group 73, then the generic health-with-death admission with -fall_hurt_zap, which forwards the selected receiver to its death-owning health with no source. Its fatal landing makes no animation request. It stores group 74 as the death-animation override, applies health -256 through that same admission and then clears the falling byte. A fatal landing on a support whose stored classification is steep (2) instead raises the controller’s pending action flag and does nothing else: no override, no health change, and falling stays set.

Ordinary landing animation selection

After threshold handling admits an ordinary landing, low falling state 8 requests group 67 without a burning torch or 68 with one when the selected player is not holding a weapon; otherwise it requests 130. Low state 9 similarly requests 69 or 70 without that selected-player weapon predicate, or 131 with it. These branches read the selected player’s weapon state, which is distinct from the landing actor’s weapon state.

Other falling states request 65 without a burning torch or 66 with one when the landing actor is unarmed. A weapon-holding actor requests 114 unless its current group is 115 or 116. All these landing requests use ordinary animation arbitration and clear falling after dispatch. The retained death-response byte is set to 8 by the actor death notification service.

Nonplayer health mutation

The shared health service returns without mutation when attribute 120 is nonzero. With attribute 97 nonzero, it also returns when the actor is neither holding a weapon nor in combat mode with packed bit 2 set.

Nonplayer health is attribute 3. Add the signed health change using wrapping 32-bit arithmetic, then clamp the signed result to 0 through 255. A result of zero dispatches death animation and notification. For an unarmed actor, force group 74 when falling is nonzero or current group is 114, 116, 130 or 131; otherwise force 134. Death notification sets the retained response byte to 8. Armed death has separate combat animation and state services. Selected-player health uses a separate service rather than mutating this attribute byte.

Stable recovery probe

The late stable-position recovery probe translates the actor’s query position forward by 6144 Q8 units at its local heading, then converts all coordinates to integer map units. Its vertical segment starts at that Y plus the actor’s positive Y extent minus post_collide_height and ends at that Y plus the extent plus post_collide_height.

Recovery prepares its own ordered static, live-actor and transient candidate lists. A current model supplies a search radius of twice its header radius, truncated toward zero. With a current model, admission uses the effective query position. Without a current model the search radius is 200 map units and admission uses local position. The actor’s own current model instance is excluded.

It visits its prepared face-model candidates in order with sidedness disabled. The first contact with normal classification 4 accepts recovery and writes local position to the probe’s integer X/Z multiplied by 256 and contact integer Y minus the positive extent, also multiplied by 256. It does not add standing height or rank competing faces.

When no model contact accepts, terrain height truncated toward zero accepts recovery if it lies inclusively between both segment endpoints. Terrain acceptance does not write the actor position. With no animation receiver the probe accepts before those segment tests. Candidate preparation precedes that receiver check and is distinct from the ordinary retained collision list.

Stable recovery response

The ordinary script wrapper retains a byte collision-response age. After its admitted script work, an all-zero packed response record clears the age to zero. Otherwise, an age below 200 adds the shared nominal tick increment with byte wrapping; an age at least 200 is unchanged. The wrapper then clears the packed response record and overlap contact identifier. Body-response and collision transition marks occupy separate bytes of that packed record.

A nonplayer stable recovery request returns without work when the stable-position record is invalid. It prepares the separate recovery query and returns when that probe accepts. On rejection, it restores the stable local position, clears attribute 6, falling and sliding, restores the saved directional movement flags and animation collision snapshot, and marks collision transition bit 1. The restored animation snapshot does not replace the ordinary default group.

The nonplayer then adds Rnd(attribute_15 * 4) - attribute_15 * 2 to local heading, wrapped to 2048. A collision-response age strictly greater than 16 also runs the bounds-segment obstacle response. The recovery marks the shared position-changed flag. The selected player takes neither the heading change nor the bounds response: after the shared restore (stable position, attribute 6, falling and sliding cleared, movement flags and animation snapshot, collision transition bit 1) it runs the ordinary ground response once more. When that response reports no support, the attempted position is written back, the stable-position record becomes invalid and the falling byte returns to its value before recovery.

After reserved weight is restored, ordinary collision invokes stable recovery when attribute 89 is nonzero and either sliding or falling is nonzero. Otherwise, a captured landing group of 67 through 70, 130 or 131 invokes recovery only when sliding, falling or the shared surface veto is nonzero. These checks precede the separate water rollback.

Ordinary water rollback

A nonplayer actor with no falling or queued motion rolls back when its stored surface is water, codes 1 through 4. This restores a separately retained local position and clears attribute 6. At the end of an ordinary update, a nonwater surface or active falling state replaces this record with the current local position. A water surface without falling leaves it unchanged. The record is distinct from the position captured at update entry. It also restores the directional movement flags and the animation collision snapshot, marks collision transition bit 1, and sets the shared changed flag. Selected-player actors do not take this branch.

Stable ordinary position

After collision attribute bit 0x04 ground response, an actor with queued motion, falling and sliding all zero marks its stable-position record valid and copies all three current local Q8 coordinates into that record. An update with any of those motion states nonzero retains the existing stable record and validity. This record is distinct from the position saved at update entry. Jump admission clears its validity before initializing queued motion.

Ordinary slope response

Slope response reads [game] slide_speed from SYSTEM.INI, clamped to at least 8 during settings loading. It uses the current primary support result. With no support or a classification other than 2, it requests ordinary group 75, or 77 with a burning torch, unless the current group is already 75 through 78. This fallback does not change sliding state, distance or position.

For class 2, the horizontal support normal supplies the quantized movement heading. The comparison heading is local for an unattached actor and effective for a family actor. A signed wrapped heading difference with magnitude below 512 selects a forward slide, groups 75 or 77, and movement bits 0x30. Other differences select a backward-facing slide, groups 76 or 78, and bits 0xc0. Backward-facing actors turn toward movement heading plus 1024; both branches translate along the movement heading.

Turning precedes the slide animation request. It uses attribute 15 when neither holding a weapon nor in combat mode, and attribute 21 otherwise. The turn rate is the signed wrapping product of that byte and frame scale, shifted right by 8, then clamped to at least 8. Differences within that rate snap to the target without requesting a turn animation. Larger differences turn by the rate and request an ordinary turn group when an animation receiver exists. Without a held weapon these are positive 14 or torch 16, and negative 15 or torch 17. With a held weapon they are positive 96 and negative 97. Combat mode affects rate selection independently of the held-weapon animation branch. Heading writes wrap to 2048. The turn helper returns zero when the desired heading already matches or the turn snaps to it. Otherwise it returns the signed heading difference before applying the turn step. For the selected player the turn also rebuilds the actor’s orientation matrix from its angles (identity, then negated yaw, pitch and roll) and copies the angles to the angle history; it changes no camera state.

The first slide forces its slide group; subsequent slides request it ordinarily. Distance is the signed wrapping product slide_speed * 128 * frame_scale, shifted right by 8. Only a positive distance translates X/Z. Primary support is queried again with the original response probe distance; an available result replaces local actor-origin Y. The first slide clears accumulated sliding distance, then every class-2 response adds the computed distance, including nonpositive values, and sets sliding state to one.

Slide termination

When the ground response finds support and the sliding-surface result is clear (or the native return-state byte is nonzero), a nonzero sliding byte ends the slide. If the accumulated sliding distance exceeds SYSTEM.INI [game] slide_hurt_height * 256, the actor first takes directional displacement of Q8 distance 0x800 (direction 2 in groups 75 and 77, direction 3 otherwise), then requests group 73 and changes health by -slide_hurt_zap; the selected player instead stores death override group 74 (no animation request) and takes the health change through its death-owning health. The sliding byte then clears. The selected player also takes the hurt branch whenever its steep-landing flag (the controller’s pending action flag) is set, whatever the slide distance.

Initial falling bookkeeping

When the ordinary support response misses and starts a fall, it records local Q8 Y plus 256 * attribute 32 as the fall origin and sets the byte timer to 30. The ordinary falling byte becomes one. Static-model actors then run the vertical writer without an animation request. An animated actor’s initial unarmed request is forced group 56 without a burning torch or 57 with one; a weapon-holding actor forces 113 unless current group is 115.

Animated entry also has separate selector, stable-position recovery and horizontal-displacement branches before this initialization. When either directional-state byte has a low bit set, the recovery branch clears those two bits in both bytes, restores all three coordinates from the stable position record, runs the ordinary jump entry with requested motion 8, forces group 35 with a burning torch or 34 without, runs the queued-motion arbitration once and ends the update’s fall handling. Current groups 18 and 30 have an exit-marker rollback branch and otherwise force 59 or 60. For the exit-marker branch, restore all three coordinates from the stable position record and force the current default group, then return without starting a fall. Without that marker, record the ordinary fall origin and timer, set falling to one and force 59 without a burning torch or 60 with one. These entry branches are distinct from continuation of an existing fall.

Jump selector at a support miss

An animated actor that misses support without falling first tests the runtime jump selector. A selector whose distance from 24 is below four (and nonzero) starts the ordinary jump entry for it, which selects queued motion 24 and forces group 85, and the support miss ends there: the walk-off recovery, the fall start and the edge service do not run. Other selectors leave the miss to those services.

Falling animation continuation

For an animated actor already falling without support, the edge service runs before the continuation request. When it does not handle the actor, low falling state 3 requests group 63 without a burning torch or 64 with one. A set high bit with no burning torch otherwise requests group 58. These cases precede the short-distance motion variants.

Falling byte 8 with absolute local Q8 Y distance from the fall origin strictly below 32768 requests group 59 without a burning torch or 60 with one. Byte 9 under the same condition requests 61 or 62. Other ordinary unarmed continuation requests group 56 or 57 according to the torch-burning counter. An actor holding a weapon instead forces group 113 unless its current group is 115. The vertical writer runs after this request, reading the resulting animation’s model-controlled vertical-motion marker.

Selected-player ledge entry

Ledge entry lets the selected player catch a ledge while falling or during queued motion, hang from it, move along it and climb onto it. It uses the living-state byte, the sliding, falling and queued-motion bytes, the retained ledge-support actor reference, a retained ledge point and ledge heading, and the global action-inhibition countdown. Ledge living states are 10 through 19. Coordinates use Y increasing downward. The positive Y extent reaches from the actor origin down to its feet; the negative Y extent reaches up to its head.

Edge service

The edge service returns zero unless the actor is the selected player, attribute 105 is not one, the torch-burning counter is zero, and neither living state 33 or 34 nor current group 149 or 150 blocks it. Those block only while animation is enabled and shell context is clear. Then:

• Stored surface 2 or 4 returns zero. In living state 15 it first runs the hang release and then the ledge transition once.
• Living states 10 through 19 return one without other work.
• Any other nonzero living state returns zero.
• Living state zero becomes 19, the ledge-support reference is cleared and the ledge transition runs once. A nonzero resulting living state clears the sliding, falling and queued-motion bytes and sets the action-inhibition countdown to 16. A zero resulting state with a nonzero action-transition counter clears bit 0x80 of the queued-motion and falling bytes. The service returns the transition’s result.

The ground response calls the service for an animated actor without support. An actor already falling calls it before the continuation request; an actor starting to fall calls it after its initial fall request. A nonzero result clears the falling byte and ends that update’s fall handling. Queued motion arbitration also calls it; a nonzero result clears queued motion and returns handled.

Player initialization clears the action-inhibition countdown. Each update subtracts the whole nominal ticks; a countdown that would not stay positive becomes zero.

Per-update ledge dispatch

An actor whose ground-response bit 0x04 is set and whose living state is 10 through 19 runs the ledge transition once per update in place of the ordinary motion and ground response; weapon-draw states 20 and 21 keep their own branch. For an actor other than the selected player the transition changes nothing. When the sliding, falling and queued-motion bytes are all zero afterwards, the stable-position-valid flag becomes one and the current position is retained as the stable position, including when the transition ended in state 18 or cleared the state. Nonzero bytes leave the stable record unchanged. The update does not run the body-contact response of states other than 0, 15 and 27 through 32.

No ledge candidate

When the ledge scan finds no record, entry from living state zero sets living state 19, selects nothing, sets the living state back to zero and returns zero. Sliding, falling, queued motion and the action-inhibition countdown are unchanged, except for the bit 0x80 clear above when the action-transition counter is nonzero. The ledge-support reference stays cleared. The scan changes no actor state, so the caller continues its ordinary fall or queued-motion handling exactly as if the service had not run. A weapon-holding actor or a nonzero action-transition counter always takes this path.

Ledge transition

The transition returns zero without changes unless the actor is the selected player, attribute 105 is not one and the living state is 10 through 19. It clears the global hang-model reference. A nonzero torch-burning counter or the state-33/34 or group-149/150 block runs the hang release and returns zero. Otherwise states are handled in the table’s order within one call; a state set by one row is handled by later rows in the same call.

Other ledge states return zero. A ledge reached from a fall or queued motion can only produce class 3 records (see classification), so a successful catch passes states 19, 14 and 15 in one call and returns 1.

An offset d at heading h adds round(d × sine[u]) to X and round(d × sine[u + 512]) to Z, with u = (−h) & 2047 and the shared floating-point sine table. Ledge heading plus 1024 points from the wall back toward open space. lag is max(0, command_cursor − command_count / 2) × 256 for the current group’s signed command cursor and command count, and zero while animation is disabled. The climb tables are indexed by real_frame without a bound check:

Hanging sidestep

A left or right sidestep in living state 15 is admitted when the ledge scan, run with the actor shifted along its own X axis, still finds a class 3 record for the hand. The shift is the actor’s X extent on that side (the negative extent to the left, the positive to the right) plus attribute 10, in whole map units, rotated by the actor matrix; X and Z change and Y stays. The original position is restored whatever the result. An admitted step requests animation group 28 (left) or 29 (right) and, with the animation system enabled, continues until that group is current. It then sets the left or right update indicator, which the hanging transition reads, and moves the actor along its own X axis by attribute 10 times the frame-scaled step ramp, with no translation while the current animation’s BreakPoint marker is set.

Ledge hang release

For the selected player in living state 15 with a zero action-inhibition countdown, set living state 17, clear the ledge-support reference and run the transition. A nonzero resulting state clears the sliding, falling and queued-motion bytes. Other states, and a nonzero countdown, change nothing.

Ledge climb request

For the selected player in living state 15, scan and select the hand-nearest class 3 record. Without one, or with record byte 2 zero, return 1 and keep hanging. Otherwise set the ledge-support reference to the record’s actor, set state 16 and run the transition; a nonzero resulting state clears the sliding, falling and queued-motion bytes. Return the transition’s result.

Ledge hang pose

Let g be the grip-0 vertex of the first ShowFrame of the actor’s animation group 7, from the animation-vertex query in Q8 integers. Set X/Z to the ledge point plus high_forward[0] × 256 at ledge heading plus 1024, and Y to ledge_Y + standing_height × 256 + abs(g.y) + 512. Without a group 7 frame nothing is written.

Ledge support below the origin

A vertical model segment runs at integer current X/Z from Y plus the positive Y extent up to Y. The smallest contact Y among classes 4 and 2 is kept; with terrain enabled, a terrain height strictly between Y and that value replaces it. The result is selected × 256 − current_Y, or 256000 without a selection.

Ledge scan

The scan clears the four-record ledge table and disables polygon sidedness for its duration, re-enabling it afterward. It finds nothing when the action-transition counter is nonzero or the actor holds a weapon. Otherwise it runs one pass at forward offset p = 0 and, when that returns zero, a second at p = 6144 (Q8). The result is 1 when a class 1 record exists, else 2 for class 2, else 3 for class 3, else 0.

Each pass:

1. Build a segment from actor-local Q8 (0, 40960, 9728 + p) to (0, −40960, 9728 + p), rotated by the actor’s orientation matrix, added to the current position and shifted right eight.
2. Query each prepared model candidate with the integer ground-probe adapter, classifying contacts with the surface classification. Keep the class 4 contact with the strictly greatest fraction as that candidate’s top (zero fractions never qualify). Class 8 contacts from candidates whose type lacks bit 0x08 append their Y to an underside list shared by the pass.
3. For a candidate with a top, while fewer than four records exist, build a horizontal wall segment from local (0, 0, 9728 + p) to (0, 0, p), rotated and positioned as above, at Y = top Y + 16. Over all candidates keep the class 1 contact with the strictly greatest fraction whose normal’s facing heading (its displacement heading plus 1024) is within 256 of the actor heading, differences wrapped by 2047. No such wall adds no record.
4. Repeat the wall segment 24 units lower: any such facing class 1 contact sets record byte 0 to one, otherwise zero. Append a record with byte 0, ledge point (wall_X, top_Y, wall_Z) × 256, the top’s model, the record heading (the wall normal’s facing heading) and the ledge-support actor (the wall candidate’s actor, zero when it has none). A fifth record is not guarded against.

Ledge record classification

Let Y be the integer current Y, neg and pos the Y extents, reach = max(14, fall_step >> 9) with fall_step the nonpositive-timer falling step min(post_collide_height × 512 − 256, attribute_32 × factor[0] × (fine_tick_increment + 2)), and hand_Y = Y + (g.y >> 8) for the group 7 grip vertex g, or Y − 1000 without that frame. For each record with top Y t:

• With falling or queued motion nonzero, or living state 14 through 17: class 3 in living state 15 or when abs(hand_Y − t) < reach, else 0.
• Otherwise: class 2 when Y − neg − reach <= t < Y − (neg >> 2); class 1 when Y − (neg >> 2) <= t < Y + pos − post_collide_height; else 0.

Then an underside Y with abs(t − underside) < 8 sets class 0. For a nonzero class:

• Outside living state 15, a wrapped heading difference above 256 between actor and record heading sets class 0 and skips the fit test.
• The fit test places the actor’s collision spheres, with its current angles, at the wall point plus offset 4096 at the record heading and Y (t − pos − standing_height) × 256. Candidates are tested in order; a body contact fails the body test and ends the loop. Until then each candidate is also tested with one sphere of radius post_collide_height >> 1 centered pos − (post_collide_height >> 1) below that Y; a class 8 contact fails the head test.
• A failed body test sets classes 1 and 2 to 0. For class 3, record byte 2 is 0 when the head test failed, otherwise 1 when the body test passed and 0 when it failed.

The hand-nearest class 3 record minimizes abs(t × 256 − (local_Y + g.y)), earliest on ties, and does not exist without a group 7 frame. Other selections take the first record of the class.

Ordinary jump entry

Jump entry requires no active native motion task, queued motion, falling or sliding, and actor state zero or 15. Selected-player edge and water gates run separately. State 15 dispatches its separate exit service instead of this ordinary initialization.

For ordinary initialization, clear the stable-position-valid flag, record current local Q8 Y as fall origin, set the byte fall timer to zero and clear accumulated sliding distance. With the runtime jump selector zero, current group 18 selects queued 9 and request 36 when the requested motion is 9, otherwise queued 8 and request 34. Current group 30 similarly requests 37 or 35. Other current groups select queued 1 and request 32 without a burning torch, or 33 with a burning torch. A nonzero runtime jump selector instead selects queued 24 and forces group 85. Set motion direction to 2 after the request.

The controller itself reads no surface state: water and lava surfaces change its behavior only through the movement helpers and the support response it calls.

Script Jump

The zero-argument SOUP function Jump returns zero immediately, including when admission refuses or an edge service handles the call. It does not wait for the jump animation or landing.

Admission refuses a selected player with a nonzero conditional controller countdown. It also refuses surface 2 or 4, any active native task, nonzero queued, falling or sliding motion, and living states other than 0 or 15. Groups 114, 116, 130 and 131 refuse admission. For the selected player with attribute 105 equal to one, all water surfaces 1 through 4 refuse admission.

After admission, clear the stable-position-valid flag. Living state 15 runs hang release and returns. Otherwise run selected-player edge entry; a handled entry returns before initializing queued motion.

Ordinary initialization records current local Q8 Y as fall origin, clears the fall timer and accumulated sliding distance, then chooses the queued motion and animation request below. A nonzero runtime jump selector overrides all rows, selecting queued motion 24 and forcing group 85.

All non-forced rows use the ordinary animation request with reverse zero. After the request, set motion direction to 2. The script native does not select the backward queued state 9 used by the parameterized ordinary jump entry.

Jump-key arbitration

While the jump key is held, every ordinary controller update after movement dispatch runs one arbitration with mask 1; the rope branch has its own jump-off service. The arbitration does nothing when either directional-state byte already has the mask bit set. Otherwise:

• A current group from 65 through 74, a nonzero queued byte or a nonzero falling byte clears the low two bits of both directional-state bytes and ends the arbitration. The sliding byte is not tested here.
• Otherwise a step-hold condition is true when attribute 11 is zero or the motion byte’s step field (bits 4 and 5) equals 3. With the step-hold condition true and either current group 18 or 30, a clear exit marker sets the low two bits of both directional-state bytes and clears the byte at +0x1be. Any other state calls the ordinary jump entry. This jump start refuses, without any state change, while the actor stands on surface 2 or 4 (deep water), while its current group is 114, 116, 130 or 131, and while its falling byte is nonzero.

This is the only writer that sets the directional-state low bits. The ordinary jump entry also refuses the selected player while the conditional preliminary countdown is nonzero, so a nonzero queued or falling byte, or a nonzero sliding byte, ends the call without effect.

Jump window

Every actor update, after its script stage and before its ordinary movement, adds the whole nominal ticks to a byte counter. When the counter exceeds 36 the second directional-state byte receives the first byte’s bits, the first byte clears and the counter returns to zero. A nonzero queued byte, or a current group other than 18 and 30, clears the low two bits of both bytes. Then a set low bit of the second byte clears the low two bits of both bytes and starts the ordinary jump entry with requested motion 8; otherwise a set second bit does the same with requested motion 9. The pending first byte therefore survives for up to 36 ticks while a run or walk jump group loops, which is the window in which a support miss takes the walk-off recovery.

For the selected player the entry runs the following before the ordinary initialization, in order: it refuses while the conditional preliminary countdown is nonzero, while a rope is attached, while the queued, falling or sliding byte is nonzero, outside living states zero and 15, and in water or lava surfaces when attribute 105 is one. It clears the stable-position-valid flag. Living state 15 then runs the hang release instead of starting a jump, and living state zero runs the ledge entry (the edge service without the water exit, the action-inhibition countdown and the fall-bit clear); a ledge held by either ends the entry.

Queued motion arbitration

A zero queued byte returns unhandled. Low queued state 3 requires group 49 when the torch-burning counter is zero, or group 50 when it is nonzero. An unavailable required group clears queued motion and returns unhandled. A different current group returns unhandled without a burning torch, but handled with a burning torch. These branches do not read the living-state byte.

Pending groups 32 through 37 and 111 defer queued motion and return unhandled. A successful selected-player edge service clears queued motion and returns handled. Other admitted queued states make an ordinary animation request before vertical advancement:

Other nonzero queued states advance vertically without this animation request. After vertical advancement, a cleared queued byte returns handled. Otherwise, clearance strictly below (positive_Y_extent - 4) * 256 clears queued motion and restores all previous local position coordinates; the result remains handled.

Ordinary ground prevalidation

Ground prevalidation uses a shared guard reset at ordinary-wrapper entry. The first call marks the guard used before checking collision attributes. Later calls return without changing the retained position rollback veto or sliding-surface result, even when collision candidates or actor attributes have changed.

The first call bypasses geometry queries when collision attribute bit 2 is clear, or for the designated player while its support-history counter is nonzero. This bypass clears both retained results. Other actors are not excluded by the counter.

It queries current and previous effective positions with the post-collision height as vertical half-length. Face contacts use the forward steep-surface midpoint ranking above, followed by terrain height comparison. This scan does not apply the queued-motion candidate-type exclusion. When local X and Z have not changed, the current result also serves as the previous result.

If both queries miss, both results clear. When exactly one query misses, the classification of the missing side is read from uninitialised stack memory and is not defined. Classification 4 at both positions also clears both. Classification 2 at both positions permits motion and marks the sliding-surface result. For a current class 2 after another previous class, subtract the motion heading from the current normal heading minus 1024 and wrap to 2048. Values below 512 or above 1535 request rollback and clear sliding. For other directions, motion permits sliding only when attribute 89 is zero and the current animation group is neither the retained default group nor any of groups 20 through 27. Otherwise it requests rollback. Other current classes clear both results.

The wrapper applies rollback by restoring all three previous local position coordinates, clearing the retained movement flags, and running the ordinary obstacle transition before the main support query.

The ground response reads the sliding-surface result after it has assigned the support height to the actor’s Y. A set result with a zero native return-state byte clears the falling byte, runs the ordinary slope response and ends the ground response without its remaining handling. With a nonzero native return-state byte the result is ignored. The rollback result is read only by the wrapper.

Forward ground-support admission

The forward ground check saves the actor position, queries support at the proposed position, then restores all three position coordinates before deciding whether the attempt succeeds. The support query retains its other state changes.

The attempt fails when collision attribute bit 2 is set and the resulting support classification is 2. It also fails when support is absent or the shared surface veto equals one. Bypassing the earlier slope check does not bypass this final classification check.

When the surface-state updater reaches its ordinary assignment path, it sets the shared veto to one for actor surface states 5 and 11, and zero for other states. Its early-return paths do not perform that assignment. The forward check reads the shared veto after the support query; it does not recompute it solely from the actor’s current surface state.

Surface-query state retention

The surface query has separate return, actor-surface and shared-veto results. An excluded query returns zero without replacing the actor’s surface or the shared veto. An admitted query can also run without assigning actor state: it returns the resolved model or terrain surface, but retains both the actor’s surface and the shared veto. For other support kinds, this path returns zero.

Queued motion, either directional-state byte with either low bit set, or the selected-player surface exclusion cause the excluded-query result. With those gates clear, falling, sliding, or living states 27 through 29 select the return-without-assignment path. Other ordinary actors take the assignment path.

The ordinary assignment path stores the resolved surface in the actor, then sets the shared veto according to that stored value. Model contacts use the packed face texture assignment; terrain contacts use the actor’s integer map X/Z position. Other support kinds assign surface zero. A zero return alone therefore does not establish that the actor’s surface or shared veto is zero.

The ordinary support wrapper captures the actor’s previous surface before querying support. It commits the designated-player support-history result, then invokes the surface updater only when collision attribute mask 0x04 is set. This invocation is not conditional on finding support: a miss supplies the cleared source kind to the updater. With that attribute mask clear, the wrapper does not refresh the actor’s surface or shared veto.

Surface-transition handling compares the updater’s return value with the saved actor surface, rather than checking only whether assignment changed the actor. Water surfaces are values 1 through 4; lava is value 5. When both the previous and current actor surfaces are outside water and lava, this wrapper does not produce water/lava transition effects.

Water and lava transition effects

The effects below run only for the selected player, only when the surface updater ran (collision attribute mask 0x04) and its returned value differs from the saved previous surface. Let P be the saved previous surface and S the actor’s stored surface after the update; the predicates read S. An update that takes the excluded-query result returns zero without storing, so with a nonzero P the comparison fires and the predicates read the unchanged stored surface; the return-without-assignment path returns the resolved surface, which equals P when the surface did not change.

• S is outside 1 through 4 and P is 0 or above 4 (not in water before or now): when S is 5 or P is 5, one effect of identifier 0x2580 is created at the actor; otherwise nothing happens. Each effect is the AddFlatEffect native with zero spread and speed one, placed at the actor’s X and Z moved eight map units (0x800 in Q8) toward the camera, along the bearing from the camera to the actor, at the support height truncated toward zero plus standing_height (map units, scaled to Q8) plus 0x600.
• Otherwise (in water now or before):
  1. Animation request. S not 2 or 4 and P equal to 2 or 4 (leaving deep water): the actor’s current animation motion byte 2 or 6 requests group 18, or group 30 while the torch-burning counter is nonzero; any other motion byte requests group 19, or 23 with the torch. S equal to 2 or 4 (in deep water): motion byte 2 or 6 requests group 142, any other motion byte group 143. Shallow-to-shallow changes request nothing.
  2. One effect of identifier 0x2500 is created, placed as above.
  3. A positional sound at the actor with volume zero and a rate offset equal to a random value below 64 minus 32: effect 70 when S is outside 1 through 4 (left the water); otherwise effect 71 when P is 0 or above 4 or S is 2 or 4 (entered water, or in deep water); otherwise effect 70.

SOUP IsInDeepWater() reads the receiving actor’s stored surface state. It returns one for states 2 and 4, and zero for every other state. It does not perform a new terrain or support query.

Converting support height to actor position

The selected ground surface height is not the actor origin height. For ordinary support, truncate the selected surface height toward zero in map units, subtract the actor’s positive Y extent, multiply by 256, and add the configured standing_height converted to runtime units. Ground-query eligibility and the later movement response remain separate from this conversion.

Applying ordinary ground support

In an ordinary grounded update, the actor retains its previous position before walking changes X and Z. The subsequent obstacle pass and support query precede the ground response. When ordinary ground support is available and no airborne or special movement state diverts the response, the response assigns the returned actor height to Y. It preserves the translated X/Z and the saved previous position. This is a discrete support-height assignment, not vertical interpolation toward the terrain surface.

Terrain support sampling

The ground query converts actor coordinates to integer map units by arithmetic right shift by eight before sampling terrain. Fractional runtime coordinates therefore do not reach the terrain interpolator. This coordinate conversion is separate from truncating the resulting surface height toward zero.

Terrain cell selection rounds map_x / 256 - 0.5 and map_z / 256 + 0.5 to the nearest integer, with ties going to the even integer. Let the selected cell coordinates be i and j. Its four horizontal corners are (256i, 256j), (256(i+1), 256j), (256i, 256(j-1)) and (256(i+1), 256(j-1)). The diagonal joins the first and last corners. If map_x - 256i is strictly greater than 256j - map_z, use the triangle containing the second corner; otherwise use the triangle containing the third. The surface height comes from that triangle’s plane. Its normalized face normal is multiplied by 256 and rounded to nearest-even for the integer contact normal; it is not an interpolated shading normal.

For interior terrain cells, runtime grid row j corresponds to WLD source row 256-j. Near-camera queries use the current terrain vertex cache; queries more than 15 grid cells away on either axis use decoded heightmap values directly.

Ordinary actor collision-shape initialization

The ordinary actor loader copies the primary MPSZ record when an animation model table and a nonnegative primary bounds index are present. A static-model actor with an MPOB model_id other than -1 also takes the primary-record path. The copied bounds supply the sphere builder with the actor’s signed RAEX radius scale. The builder replaces the record’s orientation byte according to its dominant-axis comparisons.

A static-model actor with model_id -1 derives its bounds from the loaded model’s vertices. Positive and negative extents start at zero. Vertices are visited in stored order; each component that extends the current signed extent replaces it after nearest-even integer conversion. Negative extents then become nonnegative magnitudes. The positive and negative X/Z extents are multiplied by SYSTEM.INI sphere_object_scale and shifted right by eight; Y extents are not scaled. A nonpositive system scale uses 256. Each total is the sum of its two extents, and the center offsets are zero. The usual sphere builder then applies the separate RAEX radius scale.

An actor with neither that static model nor an applicable primary-record path receives positive and negative extents of 12, totals of 24, zero center offsets, and one sphere centered at zero with radius 12. This bypasses the usual sphere builder. This initialization precedes the type-one placed-model fallback; loading a placement model afterward does not rerun collision-shape initialization.

Upright actor collision spheres

For bounds whose X and Z totals are not strictly greater than both other totals, the ordinary collision shape is a vertical series of spheres. Its unscaled radius is half the larger X/Z total, truncated, with a minimum of 4 map units. The sphere spacing is three times half that radius, with the division performed first. The available height is total Y minus SYSTEM.INI post_collide_height; a negative available height is replaced by post_collide_height. The sphere count is the available height divided by the spacing, truncated, with a minimum of two.

The radius scale comes from the signed RAEX field at 0x12. Nonpositive scales select 256; the scaled radius is the integer product of radius and scale shifted right by eight. All spheres have X and Z centers zero. All except the last start at Y = radius minus the negative Y extent, increasing by the spacing. The last center is positive Y extent minus post_collide_height minus scaled radius.

For ISLAND Cyrus, totals (48, 128, 49), positive Y extent 62, negative Y extent 66, post-collision height 50 and the default radius scale produce two radius-24 spheres at local Y −42 and −12. An additional support sphere is stored separately and is excluded from the ordinary obstacle-query count. X- and Z-dominant shapes use different construction rules.

Horizontal actor collision spheres

An X total strictly greater than both Y and Z selects the X-dominant shape. Otherwise, a Z total strictly greater than both X and Y selects the Z-dominant shape. Every tie selects the upright shape.

The horizontal shape starts with radius max(4, max(other totals) / 2), using signed integer division. If post_collide_height < 2 * radius, subtract half post_collide_height from the radius, clamp it to at least 4, and set the Y center to that radius minus the negative Y extent. Otherwise retain the radius and set the Y center to negative post_collide_height.

The spacing is (3 * radius) >> 1. The ordinary sphere count is the dominant total divided by spacing, with a minimum of one. The stored radius is (radius * scale) >> 8, using the same scale default as the upright shape. For X-dominant bounds, every ordinary sphere has the same center (radius - negative X extent, Y center, 0). The loop advances a separate accumulator without applying it to the stored X centers. For Z-dominant bounds, centers start at (0, Y center, radius - negative Z extent) and advance in Z by the spacing. Both horizontal shapes store one additional sphere copied from the first ordinary sphere; their ordinary query count excludes this copy.

The upright shape’s additional sphere has center (0, positive Y extent - scaled radius - (standing_height << 8) - 2, 0) and the same scaled radius. This expression uses the runtime-scaled standing-height value directly, while the stored sphere center is a map-coordinate value.

Per-update collision shape preparation

An actor’s selected collision shape receives its current position before the ordinary update copies the shape into working buffers. Each signed runtime coordinate is arithmetic-shifted right eight bits, then stored as a single-precision map coordinate. Each orientation component stores the integer (-angle) & 2047; these angle fields are not floating-point values.

Collision queries rebuild their orientation from these angle fields, rather than using the actor’s retained presentation matrix. Let sp, sy, and sr be shared-table sine samples at the wrapped negative pitch, yaw, and roll; cp, cy, and cr are the samples 512 entries later. The collision matrix has these rows:

Each resulting component is stored at single precision. Multiplications and additions retain extended intermediates until that store. For an upright actor this matrix maps local forward to (-sy, 0, cy), unlike the retained actor matrix’s (sy, 0, cy) mapping. The primary body query uses the selected shape’s current local coordinates and angles. Residual response uses the first working record’s copied angles, with its origin refreshed from the actor’s current effective map position.

An actor whose definition carries vertex-bound collision records (RAVC) selects a shape rebuilt from them instead of its initial shape: one sphere per record, in record order. Each center axis is the record’s model vertex divided by 256, truncating toward zero, plus the record’s signed offset on that axis, and the radius is the record’s radius. The vertex is read in model units from the actor’s current animation frame when the actor has an animated model source, otherwise from its base model. The rebuilt spheres then follow the position and orientation preparation above.

The ordinary update copies the selected shape into two working records. For upright bounds, the second record’s sphere count is increased by one, including the additional stored support sphere. The first record retains the ordinary obstacle count. X- and Z-dominant bounds retain the same count in both records. If the actor has no selected shape, this preparation uses the saved selected-player shape and the selected player’s bounds orientation instead.

Static collision list order

Static models use the same eighteen-cell spatial window as the placed-actor update list. The four corner cells are omitted. Cells are visited by increasing X within increasing Z rows, and each cell’s static list retains its existing order. For nonnegative map coordinates, static placements are assigned to cells by their X and Z coordinates divided by 512 with integer truncation. Within a cell, placements occur in reverse MPSO record order. The resulting lists are concatenated in that order before model-distance selection. Actor-only border eligibility does not remove static models. For each horizontal center coordinate, the starting map coordinate is zero below 4,608; it is 56,319 when the center plus 4,608 exceeds 65,535; otherwise it is the center minus 4,608. Divide that starting coordinate by 512 to obtain the first cell. The upper-edge start therefore occupies cell 109.

Model-distance candidate test

An ordinary actor’s collision query converts its runtime origin to integer map units by arithmetic right shift by eight. If the actor has a model, the search radius is twice the model radius, truncated to an integer. Without a model, the search radius is 200 map units. The actor’s own model is excluded.

A model passes the distance test when the squared distance from the query origin to the model placement is no greater than the square of the sum of the query radius and the model radius. Model placement coordinates and radii are floating point. The coordinate differences, squared-distance sum, and combined radius are stored at single precision before the final comparison. Equality passes.

Terrain material lookup

Terrain material queries use integer map X/Z converted to single precision. Multiply each coordinate by 1/256, subtract 0.5 from X and add 0.5 to Z, store both results at single precision, and round each to the nearest integer with ties to even. Valid grid columns are 0 through 254; valid rows are 1 through 255. Outside that range the lookup returns -1.

For valid cells, runtime row j reads WLD Map 3 source row 256-j. The returned byte retains the low-six-bit texture index and high-two-bit rotation. Surface lookup uses texture set 302 and that texture index before applying terrain blend-mask and water overrides, as described in sound surface selection.

Terrain material blend coverage

Material lookup derives local mask coordinates from integer map coordinates: u = (X >> 1) & 127, v = 127 - ((Z >> 1) & 127). The tile’s rotation selects (u,v), (127-v,u), (127-u,127-v), or (v,127-u) for rotations zero through three respectively. Call the rotated coordinates a,b.

The generated 256-by-256 mask has value clamp(2 × (x + y - 254), 0, 255) at (x,y). Terrain image indices select these coverage rules:

Start with the surface assignment for texture set 302 and the image index. Dry pixels on images 6 and 52 select sand, and dry pixels on images 31 and 32 select rock. On the other mask-backed images, zero coverage replaces a water assignment with sand; a deepwater assignment also becomes sand before the water override. Other image indices retain their base assignment.

After these rules, nonzero coverage selects surface 3, except coverage 256 selects surface 4. Coverage 255 is therefore distinct from full coverage.

Static candidate list separation

Static collision flag 2 excludes a placement before distance selection. Flag 1 routes an admitted placement to the actor-style list; other admitted placements go to the face-model list. Each list holds at most 64 entries. A full actor-style list skips further actor-style entries and continues the static scan. Encountering another admitted face model when the face-model list is full ends the static scan, including any later actor-style placements.

Ground support reads the face-model list, both for its primary segment query and its selected-player fallback sphere query. It does not query the separate actor-style list. This separation does not exclude actor-style contacts from other collision responses. The ordinary forward obstacle probe also reads only the face-model list and reports blocked when any queried model produces a sphere contact.

Each static face candidate retains its collision flag byte as support metadata. When primary or fallback support selects that candidate, the selected support receives that byte unchanged. Terrain selection instead sets support metadata to zero.

Live and transient collision candidates

Candidate construction visits prepared static placements first, ordinary live actors second, and transient models last. The face-model and actor-style lists each retain their separate limit of 64 entries across these phases.

The ordinary actor exclusion test rejects the unselected member of the two player roles. It admits the selected player and actors outside those roles. Selection zero chooses the first role; every nonzero selection chooses the second. The remaining candidate gates still apply to the selected player.

A live actor is admitted only when its ordinary actor exclusion test passes, its runtime animation-update exclusion is zero, its loaded model exists and differs from the querying actor’s model, attribute 55 is zero, and the model distance test passes. A live actor using the static model load path enters the face-model list with its actor owner and collision flags. Other admitted live actors enter the actor-style list with their actor owner. A full destination list skips that entry. When both lists are full, traversal returns before processing later live actors or transient models.

An active transient record with a loaded model and flag 0x10 enters the face-model list until that list is full. These entries have candidate type 0x80, zero collision metadata, and neither a static-placement owner nor an actor owner. They do not run the static-placement distance filter.

Actor sphere overlap

An actor does not overlap itself. Actor overlap uses each actor’s selected runtime shape, or one model-radius sphere for an actor using the static model path. At most the first 32 spheres of each shape participate. Local sphere centers receive the actor matrix transform and its shape origin truncated to integer map coordinates.

Sphere pairs are visited in shape order. The actor-to-actor query truncates the radius sum and each center difference toward zero. The distance calculation stores integer differences as single-precision values, sums their squares, computes the square root, stores that result at single precision, and converts it to an integer with nearest-even rounding. A pair overlaps only when this three-dimensional distance is strictly smaller than the truncated radius sum. The first overlapping pair returns that sum minus the rounded horizontal distance, with the vertical difference set to zero for that second distance. When no pair overlaps, the query returns zero.

An actor-style static placement contributes one sphere at its stored placement position, with the loaded model radius. The actor-to-placement query truncates each sphere radius separately toward zero before adding them. Both queries truncate center differences before the distance calculation and return horizontal separation from the first overlapping pair.

Weighted actor overlap response

For an ordinary actor, a nonzero attr_weight supplies mobility 256 - attr_weight; weight zero supplies mobility zero. Actor overlap response excludes actors with nonzero attribute 26.

Grounded living states use the same weighted actor and static-placement overlap response as ordinary standing, including weapon drawing and sheathing, states 20 and 21. They do not bypass overlap queries. The grounded state exception is 27 through 32: an actor-pair response skips the updating actor’s current support owner after the small-contact check. Other actor pairs still use weighted separation, and this exception does not change static-placement response.

An actor-to-actor separation below three map units marks contact on both actors and ends the overlap pass without displacement. For larger separation, when both mobilities are zero the updating actor returns to its previous position. Otherwise the divisor is the sum of mobilities when both are nonzero, or the nonzero mobility plus 256 when one is zero. The integer factor is 131072 / divisor. Each movable actor’s Q8 displacement distance is (factor * mobility * separation >> 9) + 255, with wrapping signed 32-bit multiplications and an arithmetic right shift. The actors move in opposite horizontal directions. A zero-mobility actor is not displaced.

An actor-style static placement does not share this divisor. An updating actor with zero mobility returns to its previous position. Otherwise the factor is 131072 / mobility and its Q8 displacement distance uses the same multiply, shift and addition expression. Static-placement separation below three still takes this response; the small-contact early return applies only to actor pairs.

For a positive actor-pair overlap, collision-attribute bit 3 on the other actor marks that actor’s body-response bit 0x04 before displacement handling. A separation below three marks body-response bit 0x04 on both actors and stores each actor’s low-word runtime identifier on the other. Weighted actor separation marks the updating actor’s body-response bit 0x04 and stores the other actor’s identifier. Both-immovable rollback does not add that mark to the updating actor. Existing result bits are preserved.

Weighted static-placement separation marks body-response bit 0x04 on the updating actor and stores contact identifier zero. Its immovable rollback does not add a result mark. Separation translates only X and Z, preserving Y. The updating actor moves away from the other origin; a movable other actor moves in the opposite direction. Coordinate addition is stored at single precision and then truncated toward zero, using the shared heading-translation rule.

Overlap marks share the body-response byte used by primary, residual, bounds and forward response. They do not write the separate rollback-result byte.

An actor-pair overlap with a separation of three or more takes a landing branch before any weighted separation when the updating actor’s falling state is nonzero, the other actor’s attribute 98 (attr_bounce_power) is nonzero, and the absolute difference between the actor’s Q8 Y and its retained fall origin is at least SYSTEM.INI [game] fall_bounce_height times 256 and the actor’s positive Y extent is greater than zero. The branch attempts to land the actor on the other actor and ends the overlap pass with body-response bit 0x80 set whether or not the landing is admitted; without these conditions the weighted response applies. The landing is not admitted when the actor is in living states 10 through 19, 27 or 28, or its surface is deepwater or scapedeepwater, or the other actor’s model link is empty, and then changes nothing else. An admitted landing makes the other actor the actor’s support, clears the actor’s sliding, falling and queued-motion bytes and its two retained motion words, sets living state 27, requests animation group 10 on the other actor, and requests the landing animation group on the actor: 114 when the actor holds a weapon (attribute 110, attr_holding_weapon, nonzero, or the drawn-weapon test), otherwise 66 when its burning-torch byte is nonzero, else 65.

The overlap pass visits its retained actor-style candidate list in order. Later queries read the positions left by earlier responses. If any weighted separation occurred and the loop completes, the forward obstacle response runs again. A small actor-pair contact returns immediately and skips this repeat, even when an earlier candidate caused weighted separation.

Ordinary forward segment response

The ordinary motion response probes a segment from the previous effective origin to the current effective origin. Both endpoints are shifted from Q8 to integer map units and receive the same caller-supplied vertical offset. It visits retained face-model candidates in order. The ordinary segment path uses the enabled polygon-sidedness flag. The model-query argument selects early return after subobject admission; it does not set polygon sidedness. Queued motion 24 excludes candidate type 0x80.

World contact points are converted to integers with nearest-even rounding. World normals are multiplied by 256, stored at single precision, and converted to integers with nearest-even rounding. Neither conversion uses the radius truncation rule. The stored contact rank is unchanged.

The motion heading comes from the horizontal current-minus-previous effective position, using wrapping integer differences and the shared quantized heading lookup. A normal’s facing heading is its horizontal displacement heading plus 1024, wrapped to 2048. Subtract the motion heading; differences below -1024 add 2047, and differences above 1024 subtract 2047. Only differences in the inclusive range -511 through 511 accept the contact.

Accepted facing contacts contribute their integer world normals in query order. An empty normal accumulator takes the next normal unchanged. Otherwise, the two normals are added, normalized to Q16, and shifted right by eight to produce the new accumulated normal. This ordered combination is not an arithmetic average of all contacts.

The chosen contact point comes from the smallest rank & 0x7fff among accepted contacts. Equal ranks retain the earlier point. Normals from later accepted contacts still contribute even when their point does not replace it. A response-disabled query reports contact without changing position. A response-enabled query truncates the first selected sphere radius toward zero and writes X and Z as point * 256 + accumulated_normal * radius, preserving Y.

Forward obstacle wrapper and motion transition

The wrapper first runs a responding forward query at vertical offset zero. A hit marks body-response bit 0x08, then runs the motion transition unless the enabled selected-player auto-grab path handles it. If queued motion or falling is nonzero, it next runs a nonresponding query at positive_y - (post_collide_height >> 2) and transitions on a hit. Finally it runs a responding query at positive_y - post_collide_height; a hit marks 0x08 and uses the same auto-grab exception before transitioning.

Living state 15 bypasses the motion transition. Living states 27 through 32, or queued motion 24, first replace queued motion with 1, living state with 0, and clear the retained integer motion vector. With queued motion zero, a nonzero falling byte marks 0x20 and becomes (falling & 0x80) | 1.

Nonzero queued motion marks 0x10, sets falling to (queued & 0x80) | 1, and clears queued motion. It records fall-origin Y as the current logical Q8 Y plus 256 * attribute 32, and sets the byte fall timer to 30. The high falling bit selects forced animation group 58. Otherwise, holding a weapon selects group 113 unless that group is already current; not holding selects group 56. These are forced requests with modifier zero, not changes to the default group. The animation-system and static-model gates still apply to the request.

The 0x08, 0x10, and 0x20 marks belong to the body-response flags, together with overlap mark 0x04, independently of rollback transition flags.

The wrapper’s auto-grab switch is enabled only when [cyrus] auto_grab equals

1. It delegates to the selected-player grabbing path before the normal motion transition; it is not a general obstacle rollback switch.

State-fifteen bounds response

Living state 15 replaces each forward motion probe with two bounds segments and returns no forward-motion hit. These segments use the retained actor matrix and current effective origin shifted to integer map units. The local endpoints are (positive_x, positive_y + 2, positive_z) to (negative_x, positive_y - 2, negative_z), and (negative_x, positive_y + 2, positive_z) to (positive_x, positive_y - 2, negative_z). Both bound records contain the stored nonnegative extent magnitudes; this query does not negate the negative extents.

The query disables polygon sidedness, visits face-model candidates in retained order, and tests both segments for each candidate before visiting the next. Queued motion 24 excludes candidate type 0x80. Integer world contacts qualify only when their normal Y component is between -41 and 160 inclusive.

Each segment tracks its own greatest negative rank and smallest positive rank, initialized to -999999 and 999999. Rank zero does not contribute. A qualifying contact contributes its full integer normal only when it strictly improves one of those bounds. Earlier contributions remain in the sum when later contacts improve a bound. The sum is not normalized. A nonzero sum adds directly to all three logical Q8 position components and marks body-response bit 0x40. The polygon-sidedness flag is restored to enabled after the query.

Sphere model admission

A sphere query first tests each body sphere against the model radius. Express the displacement from the actor origin to the model placement in actor-local axes, then subtract it from the local sphere center. The sphere passes when this squared displacement is no greater than the sum of the squared model radius and squared sphere radius. This is not the square of the sum of the radii. Only admitted spheres proceed through the actor/world/model transforms to the subgroup and polygon tests.

Collision subobject admission

The model runtime loader retains authored subobjects only for version 5 models. For other model versions, including version 4, it clears both the subobject list and its count. Version 4 subobjects therefore do not participate in these queries; the loader does not synthesize extent factors for them.

For a sphere center in model coordinates, let d be its displacement from a subobject center, R the subobject radius, e its three extent factors, and r the sphere radius. For nonzero length(d), form each component of d × R / length(d) × e and store it at single precision. The subobject passes when the squared displacement is no greater than the sum of those component squares plus r². This is not a test against the subobject radius alone.

Segment model admission

Before visiting subobjects, transform both segment endpoints into model-local coordinates and test the model radius around the model origin. An endpoint inside or on the radius passes. When both endpoints are outside, use the same bounded segment/radius test described below, without extent scaling. Here the projection may be zero: it must be nonnegative and no greater than the squared segment length. The minimum squared length is the single-precision representation of 0.1, with equality accepted.

Segment subobject admission

For segment queries, subtract the subobject center from each model-local endpoint and multiply each component by the reciprocal of its corresponding extent factor. The reciprocals and scaled endpoint components are stored at single precision. Let these scaled endpoints be a and b, and let r be the subobject radius.

An endpoint inside or on the radius admits the subobject. When both endpoints are outside, set d = a - b, L = d · d, and P = a · d. Admission requires all of the following:

• L is at least the single-precision representation of 0.1.
• P is greater than zero and no greater than L.
• (a · a) × L - P × P is no greater than r² × L.

The squared start distance, squared radius, L, and P are stored at single precision before their later comparisons. This test differs from sphere-query subobject admission.

Admitted subobjects visit their face references in authored order. Segment queries retain repeated successful face references; the successful-face suppression used by sphere queries does not apply here. Each model query stops after its first 32 successful contacts, including repeated references.

Collision face traversal

A sphere-to-model query uses the model’s authored subobject face lists. It visits actor spheres in order. For each admitted sphere, it visits admitted subobjects in their stored order and then their face references in stored order. Faces omitted from those lists do not participate in this query.

The query tracks faces that have produced a contact. Once a face succeeds, later references to that face are skipped for the remainder of the model query, including references reached by later spheres. A failed test does not mark the face: another subobject reference or another sphere may test it again. Clearing the accepted-face set between spheres, or marking every attempted face, changes this behavior. Returned contacts retain the order of first successful tests.

Selected-player fallback support

When the primary terrain/model segment query finds no support, only the designated player receives a secondary sphere query. Its world-space center is the actor’s position shifted right by eight bits plus the collision center offset. Add the positive Y extent and subtract three from the center’s Y. The radius is 10 map units when the shared support-history counter is zero, and 14 when that counter is nonzero. The query uses an identity actor rotation.

During the designated player’s admitted update, before ordinary animation and movement handling, the support-history counter decreases by the supplied nominal tick increment, saturating at zero. Other actors do not perform this decrement. After a designated-player support query, support metadata with mask 0x04 set resets the counter to 12. This also applies to support queries made while probing a temporary forward position; restoring the position does not undo the counter.

After the per-candidate actor-state exclusion, this fallback visits face-model candidates in order, then each model’s returned sphere contacts in order. It accepts the first contact whose normal classification is not side surface (1), including underside (8). It retains that contact’s model, normal, texture identity and support metadata, and returns the actor’s existing runtime Y unchanged. It does not move the actor to the contact’s projected height or rank the fallback contacts by distance. If no such contact exists, support remains absent.

For both primary and fallback model support, a steep classification (2) becomes ordinary ground (4) in the stored support state when collision-attribute bit 2 is clear. The geometric normal itself is unchanged.

Support-query misses

A support-query miss clears the selected model, source kind and classification, and sets the returned actor height to the no-support sentinel. It retains the previous contact normal, texture identity and support metadata byte. These retained fields do not constitute a valid contact when the source kind is zero.

The designated-player wrapper copies the result and tests its support metadata for the support-history reset even when the query returned no support. A retained metadata byte with mask 0x04 therefore resets the counter to 12 after a miss.

Ground-support ranking

The ordinary vertical support segment is centered on the actor’s integer map Y plus its positive Y extent, extending the supplied search distance R in both directions. Selection begins with rank 65,536 and no support. Terrain below the lower end of this segment is not a candidate. Terrain above the upper end receives rank 65,535. Terrain within the segment receives (truncate(16777216 / (2 × R)) × (truncate(terrain_Y) − segment_start_Y)) >> 8.

Queued motion 24 excludes candidate type 128 before the primary support model query. The selected-player fallback applies the same exclusion.

Model contacts with normal classification 2 or 4 compete in candidate and contact order. A contact replaces the current support when its stored segment rank is less than or equal to the current rank, so a later equal rank replaces an earlier one. Model segment ranks use the 32,768 scale described below; terrain’s rank calculation is retained separately.

Segment contact with model faces

Ground probes intersect the original model polygons. In model coordinates, let A and B be segment endpoints, V a face vertex, and N the stored face normal. The signed endpoint distances are (V − A) · N and (V − B) · N. When collision sidedness is enabled, an A distance greater than 4 rejects the face. A crossing requires one endpoint distance to be negative and the other nonnegative. A segment lying entirely in the plane is rejected.

The intersection fraction is the A distance divided by the difference between A and B distances. The intersection must pass the same oriented polygon-edge inside test as a sphere’s projected contact. The model placement transform returns the intersection and normal to world coordinates. The stored fraction uses a scale of 32,768 and nearest-integer conversion. The integer ground-probe adapter rounds world coordinates and normals multiplied by 256; it retains the stored fraction unchanged.

Sphere contact with model faces

The forward obstacle query converts the proposed actor origin to integer map units by arithmetic right shift by eight. Actor orientation transforms each local collision-sphere center; the model’s inverse placement transform then expresses the center in model coordinates. The face test uses the model’s stored face normal and polygon vertices, rather than a rendered triangle mesh.

For a sphere center C, radius r, a face vertex V, and face normal N, the signed plane distance is (V − C) · N. When collision sidedness is enabled, a distance greater than 4 map units rejects the face. Independently, a squared distance greater than r² rejects it. The candidate contact point is the perpendicular projection C + N × distance onto the face plane.

A face passes the remaining test when any polygon vertex is within the sphere, any polygon edge segment intersects the sphere, or the projected contact lies inside every oriented polygon edge. Boundary equality counts as contact. For the inside test, each consecutive vertex pair A/B must satisfy ((A − contact) × (B − contact)) · N >= 0. A face that passed for one sphere is not added again for another sphere in the same model query.

The model body-query adapter rejects working shapes with more than 24 spheres. During a model query, a subobject face scan stops when the successful-contact count reaches 32. Reaching that count is not a query failure: the returned contacts still pass through the world-coordinate integer adapter and the primary collector’s separate sixteen-contact limit.

The reported contact remains the plane projection even when a vertex or edge intersection accepted the face. The model placement transform returns the contact point and normal to world coordinates. The obstacle probe needs only whether any model reported a contact; it does not move the actor to that point.

Body-contact integer conversion

After transforming sphere contacts to world coordinates, the adapter converts contact positions to nearest integers in map units. Each world normal component is multiplied by 256, stored at single precision, then converted to a nearest integer under the default nearest-even rounding mode. It does not normalize the transformed normal again.

The ordinary body query copies these integer normals into its ordered contact list and classifies their integer Y components using the ground-normal thresholds above. Classification therefore follows world transformation and integer conversion; it is not the source polygon’s local classification.

Ordinary candidate lifetime

An admitted ordinary actor prepares its collision candidate lists before the main script wrapper. Later support, primary body and residual face queries reuse those lists. Movement and script changes do not rerun spatial admission between these stages. Query origins still follow the owning stage’s current actor position; retained candidate membership is separate from that position.

Primary body-contact collection

The primary body query retains contacts in candidate order and each model’s returned contact order. Collection returns immediately after its sixteenth model contact. Later candidates and the optional terrain contact are then omitted. When fewer than sixteen model contacts were collected, an available terrain contact is appended after them. This limit belongs to the primary body query; the residual separation query is separate.

The ordinary actor update clears the shared extra-contact append flag before animation-default and movement processing. The primary collector appends the retained normal only when that flag is set. Heightmap presence alone does not admit this extra contact. Ordinary terrain height/support queries are separate from this retained body-contact normal.

Body-contact facing admission

The primary body-response loop visits contacts in stored order. Contacts whose stored classification is ordinary ground (4) do not enter wall response. For other contacts, it computes the opposing normal heading by adding 1024 to the normal’s quantized actor heading and masking to 2047. Subtract the movement heading. Differences below −1024 add 2047; differences above 1024 subtract 2047. A contact faces movement only when the corrected difference is strictly greater than −512 and strictly less than 512. The 2047 correction makes geometric quarter-turn boundaries asymmetric: an uncorrected difference of 1536 becomes −511 and passes, whereas 512 remains 512 and fails.

The movement heading comes from the current-minus-previous X/Z displacement. When both horizontal coordinates are unchanged, the actor’s current heading is used instead. The response retains this heading across the contact loop; position or facing changes from earlier contacts do not recompute it.

Horizontal body-contact response

Body contacts are processed after the movement and ground-support response. The ordinary update runs this response only for living states 0, 15 and 27 through 32; other living states skip primary body response. The response uses the displacement from the previous position to the attempted position, including its vertical component. It normalizes that displacement to length 65536. The length divided by 65536 is stored at single precision before dividing the displacement components. Each quotient is stored at single precision before nearest-integer conversion.

For an eligible facing wall contact, the horizontal dot product is (movement_x × normal_x + movement_z × normal_z) >> 8, using the normalized movement and the contact’s integer normal. The comparison threshold is SYSTEM.INI slide_range, which is −60000 in the installed configuration. When the dot product is strictly greater than the threshold, the response subtracts the normal component from the normalized horizontal movement. Each projected component is shifted arithmetically right by four and added to the previous X or Z position. Otherwise, an actor outside the sliding state restores its previous X and Z. This step leaves Y unchanged.

Body-contact motion states

Before the dot product, each contact that passes facing admission first checks the enabled auto-grab path. When the [cyrus] auto_grab switch equals 1 and the selected-player grabbing path handles the contact, the whole primary body response ends at once: later contacts, residual separation and the rest of the response are skipped. Otherwise the contact runs the motion transition and then the dot-product test. The transition runs once per admitted facing contact, whether that contact then projects or rolls back:

• A falling actor keeps falling as (falling & 0x80) | 1 and receives the 0x20 mark.
• Queued motion becomes falling, with the 0x10 mark, fall origin, timer 30 and forced animation group of that transition.
• Living states 27 through 32, and queued motion 24, first become queued motion 1 with living state 0, then start falling the same way.
• Living state 15 is unchanged.

The response never changes Y, the fall origin or the fall timer itself. The heading-adjustment branch tests the motion bytes after this transition.

While the sliding byte is nonzero, contacts whose candidate type is 64 are skipped before classification and facing admission. A sliding actor still projects a contact above slide_range, but a contact at or below it leaves the position unchanged and sets no body-result bit.

The response counts the retained contacts minus the type-64 contacts it skipped while sliding. After the response stage, the ordinary update clears a nonzero sliding byte when that count is nonzero. The update performs this test even when the response did not run for this actor; the count then remains from the most recent primary body response.

Grounded wall-facing adjustment

After a projected wall response, an actor adjusts its heading only when its queued, falling, living-state and sliding bytes are all zero and its current X, Y or Z position differs from its previous position. The starting heading for this calculation is the attempted displacement’s quantized heading, not the actor’s current facing. Convert the contact normal to the opposing actor-facing heading by adding half a turn to its negated quantized heading and masking to 2047.

Subtract the movement heading from that normal-facing heading. Differences below −1024 add 2047; differences above 1024 subtract 2047. A positive difference subtracts up to 32 from the movement heading; a negative difference adds up to 32. Zero leaves the movement heading unchanged. This difference correction uses 2047, unlike the ordinary 2048-unit turn wrap.

Separately compare the actor’s pre-response heading with the movement heading, masking both to 2047 and wrapping their difference to the interval −1024 through 1024 using a full 2048-unit turn. When the absolute difference is greater than 512, add 1024 to the adjusted heading and mask the result to 2047.

The response stores body-result bits independently of collision attributes. A projected wall contact sets bit 1 when the ordinary heading-adjustment branch runs; otherwise it sets bit 2. Horizontal rollback also sets bit 2. Each mark preserves the other result bits. Ordinary state 15 still projects or rolls back horizontal movement, but does not enter the state-zero heading adjustment. A falling actor, or one that the motion transition has just made falling, also sets bit 2 for a projected contact and never adjusts its heading.

Residual face-contact separation

After the primary body response and the later overlap stage, the actor queries the prepared face-model list again, including admitted live models. This residual query has no primary sixteen-contact cap and does not append a terrain contact. It retains each model query’s thirty-two-contact buffer limit. Queued-motion state 24 excludes candidate type 128 from this scan. The separation distance is the current horizontal displacement length shifted right by eight, with a minimum from SYSTEM.INI poly_push_units. To obtain that length, first store each integer X/Z displacement component at single precision. Sum their squares at extended precision, store the sum at double precision, take its square root, and store the result at single precision. Convert that result to an integer using the default nearest-even rounding mode before shifting. The displacement is measured after primary body response. The installed minimum is 16. For remaining contacts, sum their integer normals, divide each component by the contact count with truncation toward zero, and normalize the result to length 65536 using the body-response normalization above. Shift each normalized component arithmetically right by eight. Add its X and Z components multiplied by the separation distance to the actor position. Y is unchanged. A nonempty contact set marks the residual-separation result even when its averaged normal has no horizontal component.

The residual query uses the first collision working record, retaining its ordinary sphere count. It rounds the first sphere’s radius to an integer and assigns a common radius to every working sphere. State 15 uses half that radius through an arithmetic right shift. Other states retain the original radius when neither falling nor queued motion is active. Queued motion or falling normally uses radius * 200 >> 8; falling with movement direction 3 uses that reduction even when its low seven state bits are zero. These working radii do not replace the actor’s retained initial shape. A nonempty residual result sets body-result bit 4 while preserving the other bits.

FPS-derived frame scale

The normal FPS measurement path counts one frame per update and accumulates elapsed BIOS ticks. A measurement window contains 18 BIOS ticks. Once at least one complete window has elapsed, measured FPS becomes the frame count divided by the number of complete windows, using integer division. The frame count resets to zero; the tick remainder is retained. A negative accumulated tick count is clamped to zero. This uses the BIOS clock, not exactly one wall-clock second; see the water clock for its frequency.

Selected blocking operations, including model resource loading, save the timing state. Restoring that state reads the current BIOS clock and uses it as the next measurement baseline, so suspended time is excluded. The restore keeps the saved frame count, measured FPS, next scale, and fractional accumulators. The FPS tick remainder, smoothed FPS, and startup countdown are not part of the saved state.

The book menu uses this save/restore pair. While it is open, each menu iteration waits for a changed BIOS tick, updates the book, advances the shared clock, and then reads input. Leaving the menu restores the saved measurement frame count, measured FPS, next scale, and nominal/fine accumulators. The measurement remainder, smoothed FPS, and remaining startup countdown retain their values from menu processing. The currently exposed movement scale and nominal/fine increments are not restored; the next clock update replaces them.

The saved baseline is relative: the last sampled BIOS tick minus the measurement baseline. Restoration subtracts that saved difference from the current BIOS tick. On the normal BIOS measurement path, measurement finishes by making its baseline equal to its sample, so a save after that measurement has a zero difference.

The FPS-derived timing path keeps a measured FPS and a smoothed FPS. On each update, the smoothed value moves toward the measured value by one. If their initial difference is at least five, it first moves by half that difference, rounded down. Thus a measured change from 19 to 17 produces smoothed values 18, then 17 on successive updates. At the acceleration boundary:

The half-difference adjustment applies to a difference of five in both directions.

use_smooth_fps selects the smoothed value instead of the measured value. The selected FPS is clamped to min_frame_rate and max_frame_rate. The target frame scale is the integer quotient of normal_frame_rate * 256 divided by that FPS. A zero configured normal rate is replaced with 12 during loading.

With use_smooth_divisor disabled, the scale becomes the target immediately. With it enabled, the scale first moves one unit toward the target. If it is still above the target, it becomes the target immediately. If it is below the target, the remaining difference determines a second increase:

An exact match receives no additional increase. This smoothing is asymmetric: a falling target can take effect immediately, while a rising target can take several updates.

The 3dfx executable also contains an alternate path driven by a reprogrammed PIT interrupt, but nothing installs that interrupt (the installer has no caller or relocation), so the BIOS-clock path above is the one that runs.

Whole nominal ticks

The computed frame scale is accumulated in units of 1/256 nominal tick. Each update’s whole-tick increment is the difference between the accumulated whole ticks after and before adding the new scale. The fractional remainder carries to the next update. A movement update can therefore receive zero animation and script ticks while still having a nonzero movement scale. Rounding each update’s scale independently, or forcing at least one animation tick per movement update, changes behavior.

A separate finer counter adds the same scale to an accumulator and shifts the total right by five bits. It therefore advances eight units per nominal tick, with five fractional bits carried between updates. Its update increment is the difference of whole counter values.

A clock reset clears the measurement frame count, tick remainder, BIOS baseline, and fractional nominal accumulator. Measured and smoothed FPS start at 12, and both the used and next scales start at 256. The reset does not seed the baseline with the current BIOS time.

The reset also starts a twelve-update startup countdown. During that countdown, the exposed movement scale is 256, the whole nominal-tick increment is 1, and the finer counter increment is 8. The underlying FPS calculation and accumulation continue. Measured FPS replaces smoothed FPS for scale selection, and divisor smoothing is bypassed. After the countdown, the exposed values use the calculated scale and accumulated increments.

Entering the world loop starts the twelve-update countdown again without resetting the measurement or accumulation state.

Related documentation

• Keyboard bindings
• System configuration
• RGM markers and actor data

Initial player animation setup

A newly allocated player actor starts with animation default group zero and stored surface state zero. Player definition and animation-group setup retain that surface value; subsequent support updates or restored world state can replace it. Player entry assigns the supplied map position with eight fractional bits and sets pitch and roll to zero and heading modulo 2048 before binding the actor definition and building its animation groups.

For an animated player definition, group setup makes two ordinary requests for group zero with modifier zero. It then clears the current model reference while retaining the selected animation model and frame identifiers. For an admitted animated actor, presentation resolves the model reference from those identifiers; a cleared reference alone does not mean that no animation frame is selected. Player entry follows that setup with a forced request for the actor’s default group, again with modifier zero. These requests use the existing shared nominal ticks; they do not establish a new clock interval.

The final request follows the ordinary forced-request rules. Requesting an already-current group before its exit marker is set only clears the pending request; it does not necessarily restart or advance the animation. The initial default group is distinct from the state-dependent default selected during subsequent ordinary player updates.

A world reload can restore temporary per-world saved state after player initialization. The restored player record replaces position and animation state; passing through marker initialization does not establish that the final loaded player is a fresh spawn. Temporary world snapshots use the map’s .TSG file. A world change saves the departing world’s temporary snapshot before the next world loads. Entering a world whose snapshot exists restores it and then places the player records at the destination marker; entering a world with no snapshot starts from its authored placement. New Game deletes every snapshot.

Player contact lists

The selected player’s update clears two contact lists at its start. Its body contact pass (run for motion states 0, 15 and 27 through 32) appends each object whose collision model the body touches to both lists once: the first list accepts an append while it holds at most sixteen entries and the second while it holds at most thirty-two. The selected player’s primary ground-support query also appends to the first list each model that becomes its best support candidate, under the same rule, and the last such model is recorded as the support owner. PlayerCollide is true when the selected player is supported by the receiver or the receiver is in the first list; PlayerCollideStatic is true when the receiver is in the second list. Hazard objects such as the swinging swords and hooks of the Drinal dungeon poll PlayerCollideStatic and damage the player on contact; the Mages Guild doors poll PlayerCollide to open.

Item Attachment System

How the engine positions held items (swords, shields) on animated characters at runtime. This is a vertex-tracking system — no skeleton or bone hierarchy exists in any Redguard format.

Overview

Character models (3D/3DC) are flat polygon meshes with per-frame vertex animation. There are no bones, joints, or named attachment points in the model data. Instead, the engine tracks a specific vertex index from the character’s animation, reads that vertex’s world position each frame, and places the held item there.

Animation commands select the character’s model and frame. Attachment vertex selection is separate from that frame selection. File ShowFrame commands must not be interpreted as vertex indices. RAEX retains the grip and scabbard vertex inputs.

Animation command stream

Groups contain packed three-byte commands. File ShowFrame commands use a twenty-bit reference into the concatenated RAAN model/frame table. The loader patches them into a runtime model handle and frame index. See animation playback and RGM.

Complete Opcode Table

Names follow UESP where available.

Opcodes 6–10 and 12–14 are implemented in the engine but do not appear in any of the 27 shipped RGM files.

Opcode Usage Census (all 27 shipped maps)

Bit Layout Summary

Frame reference patching

The loader resolves the entire twenty-bit file reference through RAAN. It rewrites the command with a runtime model handle and frame index. Neither field is an attachment vertex index.

Vertex Position Lookup

At each frame, the engine reads the tracked vertex position through this call chain:

1. Entry point — resolves animation handle and reads the tracked vertex.
2. 3D object manager — looks up handle in a table. For “virtual” animations (type 0x02), follows a parent handle chain recursively.
3. Frame builder — reads the requested vertices from the selected model frame. Frame encoding is described in 3DC.
4. Result is scaled by a global constant and rounded to integer world coordinates.

Actor model-point conversion

The runtime model-frame vertex query reads frame zero directly from its stored floating-point base vertices. Later frames with encoding nibble zero convert signed 32-bit coordinates to floating point with a factor of 1/256. Encoding nibble one subtracts signed byte deltas from the base vertex. Encoding nibble two subtracts signed 16-bit deltas from the base vertex, using a factor of 1/256 unless runtime flag 0x10 selects unscaled deltas. Each resulting coordinate is stored as single precision.

The animation-vertex query’s disable gate is the dummy 3D manager state. Initialization reads [3dmanager] dummy_manager from SYSTEM.INI, while the dm command-line option forces that state to one. Static-angle conversion, selected by [debug] convert_static_angles or the convert option, also forces dummy-manager state to one when enabled. The query’s disable comparison accepts exactly one as disabled.

A successful animation-frame vertex lookup supplies floating-point coordinates. The animation-vertex wrapper multiplies each coordinate by 256 and stores each product as single precision before converting the stored values to integers using the active floating-point rounding mode. With nearest-even rounding, half-integer ties select the even integer. It forwards the selected frame and vertex index to the model lookup. A nonpositive animation handle or an animation query-disable value equal to one returns the zero integer vector without model lookup.

The actor model-point query reads an integer vertex from the selected animation frame or the actor’s static model. It converts each coordinate to single precision before applying the actor matrix. For each transformed coordinate, it adds the actor’s local integer position before storing the sum as single precision. The integer position is not rounded to single precision separately before addition. The stored sums then convert to integer coordinates using the active floating-point rounding mode. With nearest-even rounding, half-integer ties select the even integer.

Item model data

Item definitions come from the ITEMS section of the configured item INI. Model names resolve against the loaded model registries, searching the primary registry before the secondary registry and selecting the first case-insensitive name match. The item initialization function iterates all items and populates per-item runtime fields:

World loading replaces the selected world-map filename’s extension with ROB and loads that archive into the primary model registry before initializing item geometry. Model filename resolution discards authored directory components and uses the configured art directory, whose empty-setting default is FXART\\. The inventory-item display loads INVENTRY.ROB into the secondary registry; menu presentation loads MENU.ROB into that same secondary registry. Loading a registry replaces its previous contents.

For weapon items, hand_object_file selects the hand model and hilt_object_file selects the stowed model. The hand model’s ROB segment bbox_extent_y supplies weapon length. The runtime reads that word as a signed 32-bit value before preparing the weapon’s collision spheres. The X and Z extents do not supply this length.

Attachment Transform

The drawn-weapon routine queries the signed RAEX grip vertex pair from the actor’s current animation handle and frame. It adds the supplied local offsets to each vertex with signed 32-bit wrapping, then transforms both points through the actor matrix. The transformed points supply the direction calculation.

The two-point direction subtracts the second point from the first with signed 32-bit wrapping. It computes horizontal distance from the X/Z difference using the integer distance query. With the signed bearing convention whose positive X axis is 512 and positive Z axis is zero, direction pitch is the bearing of (horizontal_distance, delta_y) minus 512. Direction heading is 1024 minus the bearing of (delta_x, delta_z). Both results are masked to 2047; direction roll is zero. Coincident points produce pitch 1536 and heading 1024.

The attachment matrix starts as identity. Its successive rotations use the negated direction heading, one quarter-turn minus the direction pitch, and the negated actor roll. Each angle is masked to 2047. The actor retains pitch plus one quarter-turn, heading, and roll, each masked to the same range.

For each attachment-position component, subtract the first transformed vertex from the second with signed 32-bit wrapping, shift the difference arithmetically right one bit, add the first vertex with wrapping, and shift that result arithmetically right eight bits. Add this integer midpoint to the actor’s floating position and store the sum as single precision. Separately, the actor retains the first transformed vertex plus its floating position multiplied by 256, converted to a signed integer by truncation.

If attachment allocation fails, the routine performs no vertex queries or transform publication.

The stowed-weapon routine uses the signed RAEX scabbard vertex pair with the same local-offset, actor-matrix and direction calculation. It builds the same matrix and retains the same angle fields. Its attachment position uses the first transformed vertex rather than the pair’s midpoint. Add that vertex to the actor’s floating position multiplied by 256 and truncate to a signed integer. Shift this integer arithmetically right eight bits and store it as single precision. An out-of-range integer conversion produces the signed minimum value before the shift.

Weapon State Machine

The weapon state machine selects which attachment routine and which model (hand vs hilt) to use based on the actor’s weapon state:

The draw/sheath frame thresholds are read from the actor’s attribute data (offsets +0x22 and +0x23 from an attribute block pointer at actor +0x272).

The collision sphere tip is offset from the grip point by item.length × -0x100, positioning it along the weapon axis for combat hit detection.

SOUP Script Interface

Scripts drive weapon state transitions through these SOUP functions:

Additional runtime state tracked per actor: hand_pos.vx/vy/vz, hand_angle.vx/vy/vz, hand_type, hand_length, weapon_drawn, hand_item.

Held-item assignment

HandItem(id) is separate from inventory selection and weapon drawing. It rejects assignment while the receiver is in deep water, on an edge, in the air, or holding a weapon. It also requires an open item system, a receiver, and execution outside the shell context. Deep water means stored surface 2 or 4; edge motion states are 10 through 19. The in-air predicate includes nonzero falling, sliding, or queued motion, and motion states 27 through 29.

After admission, the requested ID must resolve to an item record. No owned-count, visibility, or item-type check is made. Success stores the low eight bits of the ID in the actor’s held-item field. It does not change the selected inventory item, assign the weapon attribute, or immediately position or draw an attachment. The function returns zero both after assignment and after a rejected admission.

Data Flow Summary

Animation playback resolves the model and frame first. Item attachment then reads selected vertices from that model frame and computes the item transform. The frame reference and the vertex selection are distinct inputs.

External References

• UESP: Mod:RGM File Format § RAEX — RAEX field names from in-game console
• RGUnity/redguard-unity RGRGMFile.cs — RGMRAEXItem struct definition

Developer console

The Glide console accepts 82 registered commands with short aliases, plus 13 cheat names handled separately.

Command dispatch and syntax

Press F12 to open the console. Command names are case-insensitive. Each registered command has exactly the long name and short alias listed below. Other abbreviations are not accepted. The commands command, also spelled ?, lists the 82 command pairs; oracle lists the 13 cheat names and their raw state values. There is no literal cheat prefix command.

The engine also has a programmatic command entry point. It accepts the long registered names and the cheat names, but does not look up short aliases.

Input is lowercased and normalized before dispatch. A semicolon ends the input; it does not separate commands to execute in sequence. Arguments are parsed by each handler. Spaces and commas are not interchangeable: for example, use load 1,0,0, item add,ID, setflag NAME,VALUE, and object attr attr_health = 100. Square brackets in this reference indicate optional arguments and are not typed.

Most numeric handlers accept decimal integers, negative decimal integers, 0x hexadecimal values, named equates, and named SOUP flag values. An unresolved symbolic value prints a diagnostic and substitutes 1. The percent-prefixed binary-input path returns zero for ASCII binary digits. Quoted numeric input reads the first four bytes following the quote as a little-endian 32-bit value; it is not general string evaluation. delay uses decimal conversion directly.

Decimal and hexadecimal conversion consume the numeric prefix and stop at the first non-digit for that radix. Arithmetic wraps to 32 bits. A leading minus selects decimal conversion even when no digits follow, yielding zero in that case. 0x without hexadecimal digits also yields zero. A leading plus does not select numeric conversion through the console reader.

Symbol lookup checks equates, console variables, then SOUP flags. Both definition loading paths release the temporary equate table before returning. The normal console therefore has no retained definition equates, and its console-variable table is empty. SOUP flag lookup reads the current raw value, without invoking the flag’s latch operation. Flag names are matched case-insensitively; the name list is built in reverse definition order, so the last duplicate name wins.

The console keeps a selected object, a monitored object, a selected rope and a selected light. These are separate selections. An object selected for inspection does not become the monitor target until object monitor is used.

Interactive presentation and editor

The interactive console covers the game viewport with SYSTEM/PAPER.GXA. At widths of at least 640 pixels, its standard font is the FNT named by SYSTEM.INI [system] gui_low_font. The console draws that font with a single ink color rather than the glyph palette colors. Its header and left text margin start at the scaled equivalent of eight pixels in a 640 by 480 viewport. The header identifies the development console and reports memory usage; a horizontal separator precedes retained output and the command prompt.

Standard settings use palette entry zero for editing and header text. Report text uses the GUI color nearest to six-bit RGB (0, 42, 0) in the active palette. Palette matching examines entries 1 through 255 in six-bit RGB. An exact match wins immediately. White entries whose component sum is 189 are otherwise skipped. For each component, the difference is target minus candidate when nonnegative, and candidate minus target minus one otherwise. Candidates with all three differences below nine are compared by the absolute difference of their weighted RGB sums, using weights 19661, 38666 and 7209. Equal scores select the later entry. If this pass finds no candidate or its score exceeds 24, a second pass minimizes the sum of the three component differences, again preferring later ties. The sixteen console GUI color targets, in index order, are palette entry zero, then six-bit RGB (62,62,62), (42,42,42), (32,32,32), (22,22,22), (12,12,12), (32,51,63), (19,33,44), (10,17,26), (53,3,23), (49,0,0), (60,0,0), (0,30,0), (0,42,0), (0,0,0) and (24,0,28). The first index uses palette entry zero directly; the others use the matching procedure above, including black at index fourteen.

The standard GUI font’s linked font points to itself after startup. The alternate console font is a copy of that same font, with its link pointing to the copy. At widths of at least 640, font zero selects the standard font and font one selects its linked font. Below 640, font zero selects the linked font and font one selects the alternate copy. Changing the console font selector therefore does not load a different FNT file.

The console has 512 retained lines, with at most 100 characters in each editable command line. A > prompt distinguishes command lines from report lines.

F12 and Escape leave the interactive console. Left and Right move the cursor; Backspace removes the preceding character and Delete removes the following character. Typing inserts printable characters at the cursor. Up and Down select retained lines, including report lines; report lines are not editable. Tab copies a preceding command into the current editable line. Home moves to the start of the line, then to the oldest retained line when already at the start. Page Up and Page Down move through retained output. Enter dispatches an editable command. The interactive console runs its own input and drawing loop before returning to the caller’s game loop.

With shadows enabled, the Glide glyph path draws a black glyph copy before the main glyph. The console selects a two-pixel offset in each axis at widths of at least 640 and one pixel below that threshold. The standard console font uses main alpha 255; the shadow alpha is (255 * 200) >> 8, or 199.

The cursor uses two report-colored vertical-bar glyphs, four scaled pixels above and below the insertion position. It is visible while a key is being handled or when the low bit of the console clock counter is set. On the normal BIOS-clock path, the counter increments once whenever accumulated elapsed time reaches 18 BIOS ticks, retaining the remainder modulo 18. A delayed update increments it once even when several such intervals elapsed. An input iteration without a key clears the forced-visible state.

Console preferences are stored in REDGUARD.CPF.

Registered commands

Each row is one command. The alias invokes the same handler from the interactive console.

Console and diagnostics

State and scripts

Name patterns are case-insensitive. An asterisk accepts the remainder immediately, including any following pattern text. A question mark accepts one character; extra trailing question marks also match after a nonempty name ends. Empty patterns match in the shared matcher, although flag commands require a nonempty pattern.

Objects and inventory

World and navigation

Developer tests

Rendering and visibility

Lighting editor

Sky, lighting and water

Sky scale and level read signed 32-bit console numbers and convert them to float for rendering. Wave amplitude, speed and frequency do the same conversion. These five commands do not clamp their inputs. Sky speed uses the full signed value divided by sixteen for immediate scrolling, stores its low byte in the world configuration, and chooses a new random scrolling direction.

Subcommands

Comma-separated names in the first column denote separate alternatives unless the row shows an argument form such as add,id.

show

console

object

item

node

script

rope

restart

render

logplayer

logmonitor

Cheat names

These 13 names are also accepted as console commands: oracle, nodemarker, moonraker, task, animation, magiccarpet, savecheats, drevil, drno, goldfinger, neversaydie, oddjob, and yeahbaby.

oracle and savecheats perform actions. The remaining names accept a toggle or name = value. Their numeric activation conditions differ. See Cheat system for the effects and per-cheat rules.

Differences between help and command behavior

• show accepts rain, free, map, list and activelist even though its usage list omits them.
• object anim and object size are accepted but omitted from the object usage list.
• The node help lists node showinuse, but the handler does not accept that spelling. node inuse is accepted.
• fxtexturelist requires an index despite the brackets in its usage message. fxshowtexture without an index turns its preview off.
• poke has no memory-write operation. Successful byte validation is followed by a one-line hex display.
• get and set use an empty console-variable table in the Glide build. SOUP flag access through getflag and setflag is separate and uses names loaded from SOUP386.DEF.
• object zap tests argument presence backwards. Supplying an amount produces its missing-argument message; omitting it reaches decimal conversion of the empty token.
• The optional zero status in setflag XORs the flag metadata with 239, leaving the set bit unchanged and flipping the other bits. A nonzero status sets the set bit.

External references

• Redguard Console on UESP
• Cheat system
• SOUP scripting

Cheat System

Hidden cheat system built into the Redguard game engine. The 13 cheat codes are XOR-obfuscated in the binary (each byte XOR’d with 0xAA).

The developer console reference lists all other console commands and their aliases.

Activation

Cheats can be triggered in three ways:

During Gameplay (no console)

Type the cheat name on the keyboard during normal gameplay and press Enter. The engine reads keypresses every frame into a hidden 127-character input buffer. On Enter, the buffer is compared against all cheat names. No visual feedback is given — the cheat silently toggles.

Developer Console

Press F12 to open the console, type the cheat name, and press Enter. The console prints Cheat <name> turned on or Cheat <name> turned off.

Console with Explicit Value

In the console, use <cheatname> = <value> to set a specific integer value instead of toggling. For example, magiccarpet = 1 forces the cheat on, magiccarpet = 0 forces it off.

Toggle rules

Cheats normally store 0 for off or 1 for on. Typing a cheat name again switches between those two values, whether entered during gameplay or in the console.

The console also accepts other numbers, such as oddjob = 2. These are raw values, not strength levels. Their gameplay meaning depends on the cheat: some checks accept any nonzero value, while others require exactly one.

Entering the name again handles these unusual values differently:

• During gameplay, any nonzero value becomes zero.
• In the console, an even value becomes one and an odd value becomes zero.

For example, after oddjob = 2, entering oddjob in the console stores one; entering it during gameplay stores zero. The console rule is (value + 1) & 1.

oracle and savecheats run dedicated actions. oddjob follows the ordinary state-handling rules above.

Cheat List

The cheat names are themed after James Bond films (Moonraker, Dr. No, Goldfinger, Oddjob, Never Say Never Again) and Austin Powers (“Yeah Baby”).

Values other than zero and one

The Glide engine does not apply one shared on/off rule to every cheat. The ordinary gameplay checks use these conditions: