📂 View source on GitHub

SpeedCylinder Global Spawner

Overview

Spawns a SpeedCylinder (Pendulum) at Player 1's position in any level, not just Level 6 (Up). Pure CE AutoAssembler script — no bass.dll proxy required.

Files

• SpeedCylinderSpawn.CEA — CE AutoAssembler script (pure CEA, no Lua)

Installation

1. Copy SpeedCylinderSpawn.CEA to your Cheat Engine scripts folder
2. In CE: File → Load → select SpeedCylinderSpawn.CEA
3. Enable the script

Usage

1. Add the address SpawnFlag to your CE address list (Advanced → Add Address, or type "SpawnFlag" in the address bar after enabling the script)
2. Enter a race or arena (any level works)
3. Set SpawnFlag to 1 — a SpeedCylinder spawns at Player 1's current position
4. The flag auto-resets to 0 after spawning
5. Set to 1 again to spawn another

How It Works

The script hooks Scene_UpdateBallsAndState (0x41B540) which runs every frame. When SpawnFlag is set:

1. Checks if a SpeedCylinder mesh is already loaded (Board+0x4788, only set on Up Race)
2. If not, loads the mesh from levels\levelup-speedcylinder via MeshWorld_ctor
3. Finds Player 1's ball in the all_balls_list and reads its position
4. Allocates a Pendulum struct (0x150C bytes) and calls Pendulum_ctor
5. Registers the new SpeedCylinder in the Board's mechanical objects list (Board+0x2578)

Verified Addresses (Ghidra, 2026-06-22)

🔗 Related Documents

• SpeedCylinder Global Spawner
• Global Drawbridge Spawner

📂 View source on GitHub

Global Toob Race Object Spawner

Spawns any of the 10 Toob Race objects at Player 1's position in any level.

Usage

1. Set ObjectType (1-10) to select which object to spawn:
   • 1 = SPINNY (rotating platform)
   • 2 = LOOPER (looping track)
   • 3 = GEAR (spinning gear)
   • 4 = BIGGEAR (big gear)
   • 5 = ROTATOR (generic rotator, uses Blockdawg1 mesh)
   • 6 = SPEEDCYLINDER (swinging pendulum)
   • 7 = LIFTER (lifter elevator)
   • 8 = TIMEBUTTON (timed button)
   • 9 = BLOCKDAWG1 (block dog enemy 1)
   • 10 = BLOCKDAWG2 (block dog enemy 2)
2. Set SpawnObject to 1 to spawn at player position
3. Objects update automatically via vtable[0x2C] each frame

How It Works

The script bypasses the factory chain (CreateSpinny → CreateLevelObjects → etc.)
and calls constructors directly with our own MeshWorld pointer.

Key advantage over Drawbridge/PopCylinder scripts: No JIT board slot injection needed.
All Toob constructors take the mesh pointer as the last stack parameter, so we pass
our own MeshWorld directly without touching any board+0x43xx slots.

Toob Race Board Mesh Slots

Set by LevelBoard_Toob_ctor (0x41F4B0):

Additional slots set during LoadRaceData (not by board ctor):

• board+0x4784 = LIFTER mesh (runtime, unknown file)
• board+0x4788 = SPEEDCYLINDER mesh (runtime, unknown file)
• board+0x478C = TIMEBUTTON mesh (runtime, unknown file)
• board+0x47E0 = SPINNY mesh (runtime, unknown file)

For objects with unknown mesh files (SPEEDCYLINDER, LIFTER, TIMEBUTTON),
the script uses Level8-Spinny as a fallback mesh.

Constructor Summary

Factory Chain (How the Game Creates Toob Objects)

LoadRaceData("TOOBRACE")
  → reads MESHWORLD ref objects
  → for each ref, calls factory chain:
    CreateBumper (0x40FA20)     → BUMPER
    CreateSpinny (0x4143D0)     → SPINNY (→ Rotator_ctor, mesh from board+0x47E0)
    CreateSpeedCylinder (0x4117B0) → LIFTER, SPEEDCYLINDER, TIMEBUTTON
    CreateMechanicalObjects (0x417FE0) → LOOPER, GEAR, BIGGEAR, ROTATOR
    CreateLevelObjects (0x4121D0) → BRIDGE, TIPPER, BONK, POPCYLINDER, BLOCKDAWG, CATAPULT, GLUEBIE

Toob Race Collision Handler Events

The Toob collision handler at vtable[0x1D] (0x410020) handles:

• N:SPINNY, N:SAWTEETH, N:BUMPER — collision with rotating objects
• E:ALERTSAW2, E:BRANCH — event triggers
• PILLAR, MAGNIFYER, CLOUDSCAPE — special objects
• POPCYLINDER, TRAPDOOR — pop/door effects
• E:PEGS, E:TRAPPOP, E:NOPEGS — peg state machine
• E:HEATON, E:HEATOFF — heat/lava toggle
• E:LIMIT — boundary limit

Object Registration

All objects are registered in:

• board+0x2578 — active objects list (update + render)
• board+0x10EC — collision level list
• board+0x8B0+0x18 — collision dispatch list
• board+0x8AC→+0x480→+0x1C — render list (post-alpha)

Notes

• BLOCKDAWG objects need a DAWGPATH ref for movement. With pathId=0 they stay stationary.
• GEAR/BIGGEAR use dual-position params (X,Y,Z + X2,Y2,Z2). Script uses same position for both.
• SPEEDCYLINDER/LIFTER/TIMEBUTTON use fallback mesh (Level8-Spinny) since their actual
  mesh files are loaded at runtime via board+0x4784/0x4788/0x478C and the filenames
  are not known at compile time.

🔗 Related Documents

• Game Object Factory System
• Level Object Factory

📂 View source on GitHub

jump_mod v22

Press SPACE to jump (Player 1 only, raycast ground detection).

What changed from v20

v22 adds countdown and race-end gating:

1. Countdown gate: Before allowing a jump, checks Scene+0x3A4C
   (countdown_done flag). This flag is set to 1 by Scene_HandleRaceEnd
   (0x41B130) when all 3 Ready/Set/Go phases complete. If 0, the game
   itself blocks all input in Scene_vmethod31 (0x41AC70) — the jump
   mod now mirrors this behavior.

2. Race-end gate: Checks ball+0x14C (freeze flag). Set to 1 by
   Scene_HandleRaceEnd at 0x41B40D when the race timer expires
   (player touches the goal). Also checked by the game's Ball_Update
   at 0x4060A1. When set, the ball is frozen and jumping is blocked.

Both gates are checked in the input thread BEFORE running the raycast,
so denied jumps don't waste a raycast call.

What changed from v17

v20 changed ground detection from a fixed epsilon to a slope-aware
threshold (radius × 1.45):

On a slope of angle θ, a straight-down raycast hits at distance r/cos(θ)
from the ball center, not r. Using radius * 1.45 covers slopes up to
45° (cos(45°) ≈ 0.707, r/0.707 ≈ 1.414r). The 1.45 factor gives a small
safety margin beyond the theoretical minimum of √2 ≈ 1.414.

Features

• Raycast ground detection: Casts a ray straight down from the ball
  position using the game's own Mesh_FindClosestCollision (0x465D90).
  If the hit point is within radius × 1.45 of the ball Y, the ball is
  grounded and can jump.
• Countdown gating: No jumping during Ready/Set/Go countdown
  (Scene+0x3A4C == 0).
• Race-end gating: No jumping after touching the goal
  (ball+0x14C == 1).
• Airborne denial: Can't jump while in the air (raycast misses).
• Edge detection: SPACE uses rising-edge detection (one jump per keypress).
• Safety checks: Won't jump if ball pointer not yet captured or
  during fall/respawn.

Hook points

The input thread polls the keyboard (DIK_SPACE at KeyboardDevice+0x45)
every 16ms. On rising-edge keypress, it checks countdown/race-end gates,
then runs the raycast. If grounded, sets g_want_jump=1. The Phase 15
cave checks this flag and adds an upward impulse to ball+0x174 (Y force
accumulator) if set.

Files

• jump_mod_raycast.c — C source code (BASS proxy + raycast + gates)
• bass.dll — Compiled DLL (MinGW cross-compiled, PE32 i386)
• jump_mod_v22.zip — Distribution archive

Build

i686-w64-mingw32-gcc -shared -o bass.dll jump_mod_raycast.c -lwinmm \
  -Wl,--enable-stdcall-fixup -O2 -static -static-libgcc \
  -Wl,--add-stdcall-alias

🔗 Related Documents

• jump_mod v22
• Entity Limit Fixer v7

📂 View source on GitHub

No-Pause Mod v2

Prevents the pause menu from appearing via any input method — ESC key, right-click, or Win32 message pump. The game continues running normally with no pause overlay, no physics freeze, and no camera stop.

Why v1 Didn't Work

v1 only patched one of three code paths that trigger pause. Pressing ESC still paused the game through the Win32 message pump path, and right-clicking paused through the mouse event handler path.

The Three Pause Paths

Scene_CreateGameOverMenu (0x40a920) creates the pause overlay and sets scene+0x874 = 1 (pause flag). When this flag is set, GameUpdate (0x469cf0) skips calling Scene_Update on the scene — freezing all physics and game logic.

There are three independent code paths that call Scene_CreateGameOverMenu:

Path 1: DirectInput ESC Poll (Scene_Update)

Scene_Update (0x419c00)
  → Input_CheckKeyCombo(app, 2)    ; checks ESC via DirectInput
  → if pressed: Scene_CreateGameOverMenu(scene, 1)

Gating conditions: game state not in {3,4}, scene+0x220 == 0, demo timer inactive.

Path 2: Right-Click Mouse Handler (vtable[5])

App_OnMouseDown(param_3=1=right button)
  → UIWidget_HitTest → vtable[5] on Scene
  → thunk 0x4130A0 checks param_3==1, App+0x238, profile+0x95
  → if conditions met: Scene_CreateGameOverMenu

This thunk appears in 32 scene-object vtables — all scene types inherit this pause-on-right-click behavior.

Path 3: Win32 Message Pump ESC (vtable[8])

WndProc → key message dispatch → vtable[8] on Scene
  → thunk 0x40B400 checks param == 0x1B (VK_ESCAPE = 27)
  → if match: JMP Scene_CreateGameOverMenu (tail call)

This is a separate ESC detection path from Path 1. Path 1 uses DirectInput polling; Path 3 uses the Win32 message pump. Both fire on ESC press. This thunk also appears in 32 vtables.

The Patches

Three single-byte patches, one per path:

All three convert conditional jumps to unconditional jumps, causing the pause creation code to always be skipped.

How Pause Works (for reference)

1. Scene_CreateGameOverMenu (0x40a920) creates a PauseMenu or PauseArenaMenu overlay and sets scene+0x874 = 1
2. GameUpdate (0x469cf0) iterates scene objects each frame. For each object, it checks obj[0x21d] (byte at scene+0x874). When the flag is 1, it skips calling Scene_Update (vtable[1]) — freezing all game logic
3. When the player clicks "RESUME" in the pause menu, PauseMenu_HandleButtonClick sets scene+0x874 = 0 — unfreezing the game

Installation

1. Extract the zip into your Hamsterball game folder (next to Hamsterball.exe)
2. Run install.bat
3. Launch the game

Uninstallation

Run uninstall.bat to restore the original bass.dll.

Technical Details

• Mod type: BASS.dll proxy (v3 lazy loader pattern)
• Patch type: Three single-byte patches — conditional → unconditional jumps
• Patch addresses: RVA 0x19d5b, 0x130b5, 0x0b405 (VA 0x419d5b, 0x4130b5, 0x40b405)
• Side effects: None — ESC and right-click are simply ignored during gameplay. No menu, no pause, no freeze.

🔗 Related Documents

• No-Pause Mod v2
• Scene System Deep Documentatio

📂 View source on GitHub

Universal Ref Loader — Design Document

Created: 2026-06-23
Session: RodentRacer investigation into ref-loading system
Purpose: Enable loading ANY object ref into ANY race level via a DLL mod, and fix the multi-instance problem for static-mesh objects.

Table of Contents

1. Architecture Overview
2. How Ref Loading Works
3. Two Board Systems: Race vs Arena
4. Factory Dispatch via vtable[33]
5. Board Constructor Mesh Pre-Loading
6. Object Categories: Allocating vs Static vs Configuring
7. The Multi-Instance Problem
8. The Mesh Dependency Problem
9. The Difficulty Gate Problem
10. The universal ref loader Design (Option B)
11. Clone-on-Return for Static Mesh Objects (Option A)
12. Complete Object Dependency Table
13. Complete vtable[33] Mapping
14. Complete Board Slot → Mesh File Mapping
15. Key Function Addresses
16. Implementation Plan
17. Build & Test

1. Architecture Overview

Hamsterball loads level objects in a two-layer pipeline:

MESHWORLD file (Section 1: ref points)
  ↓
Scene_CreateDynamicObjects (0x40C430) — iterates ref points
  ↓  For each ref:
  ↓  calls board->vtable[33](refName, &outObj, &outCol, refEntry) at 0x40C4BA
  ↓
Factory Function (level-specific, via vtable[33])
  ↓  Matches ref name via __strnicmp
  ↓  Allocates object, calls constructor, sets position
  ↓  Returns object pointer in outObj
  ↓
Scene adds object to active list (+0x335), sets position from MESHWORLD data
  ↓  Calls object vtable[22] (Init) and vtable[21] (SetTimer)

Scene_CreateDynamicObjects (0x40C430) — Full Decompiled Flow

void __fastcall Scene_CreateDynamicObjects(int *param_1)
{
    // Iterate through MESHWORLD Section 1 ref points
    // For each ref (puVar4 = ref entry with name, x, y, z, ...):
    
    local_58 = NULL;  // output object pointer
    local_54 = 0;     // output secondary object pointer (trigger zones)
    
    // Call the Board's factory function (vtable[33], offset +0x84)
    (*(board->vtable[33]))(*puVar4, &local_58, &local_54, puVar4);
    
    if (local_58 != NULL) {
        // Object was created successfully
        Gfx_ScaleX(_DAT_004cf44c - puVar4[5]);           // set scale
        Gfx_SetPosition(puVar4[1], puVar4[2], puVar4[3]); // set position from MW data
        
        AthenaList_Append(scene + 0x335, local_58);       // add to dynamic object list
        AthenaList_Append(mw_parser + 0x1c, local_58);    // add to MW object list
        
        (*local_58->vtable[22])();    // Init/Setup
        (*local_58->vtable[21])(timer); // SetTimer
        
        if (local_54 != 0) {
            AthenaList_Append(scene + 0x43B, local_54);  // add trigger zone
            AthenaList_Append(scene_physics + 0x18, local_54);
        }
    }
    
    // Advance to next ref point
}

Key insight: The factory returns a pointer in local_58. If it's non-NULL, the scene adds it to the dynamic object list and initializes it. The position comes from the MESHWORLD ref data (puVar4[1], puVar4[2], puVar4[3]).

2. How Ref Loading Works

MESHWORLD Section 1 Ref Points

Each ref point in a MESHWORLD file contains:

• Name (string, e.g. "CATAPULT", "WATERWHEEL", "N:BUMPER")
• Position (3 floats: x, y, z)
• Rotation (3 floats: x, y, z)
• Material (4×4 float matrix + Power + reflection + texture)
• Extra params (passed as param_4 to the factory)

Ref Name → Factory Matching

The factory function uses __strnicmp to match ref name prefixes:

• "CATAPULT" matches any ref starting with "CATAPULT" (case-insensitive)
• "N:" prefix refs are handled by a separate N:/E: handler at 0x40C5D0
• "E:" prefix refs are event triggers (score, gravity, etc.)

Two Passes

1. vtable[33] factory — matches bare ref names (CATAPULT, TIPPER, etc.)
2. N:/E: handler — called from within the factory for N: and E: prefixed refs

The handler is called from 25 sites within the vtable[33] factory functions.

3. Two Board Systems: Race vs Arena

Hamsterball has TWO independent Board systems, selected by App+0x237:

Critical: Race factories handle FAR FEWER ref types than Arena factories. Levels 1, 2, 3, 9, 10, 12, 14 use ONLY the base race factory (0x4133E0) which handles only PLATFORM, STANDS, N:BUMPER. Their level-specific objects (tippers, bridges, waterwheels) are NOT created in race mode — they're loaded via the Arena Board system or are part of static geometry.

The universal ref loader should hook at 0x40C4BA (the vtable[33] call site inside Scene_CreateDynamicObjects), which intercepts BOTH Race and Arena modes.

4. Factory Dispatch via vtable[33]

The Dispatch Call Site

At address 0x0040C4BA inside Scene_CreateDynamicObjects:

; *board is in a register, vtable[33] is at offset +0x84
mov eax, [board]          ; get vtable pointer
call [eax + 0x84]        ; call vtable[33] factory
; args: refName, &outObj, &outCol, refEntry

Factory Function Signature

void __thiscall FactoryFunc(
    Board* this,           // ECX = board pointer
    const char* refName,   // [ESP+4] = ref name string from MESHWORLD
    void** outObj,         // [ESP+8] = output: created object pointer
    void** outCol,         // [ESP+0xC] = output: secondary object (trigger zone)
    RefEntry* refEntry     // [ESP+0x10] = full ref entry (name, pos, rot, material)
);

Complete vtable[33] Mapping

Race Board Factories

Arena Board Factories

Key insight: Levels 1, 2, 3, 9, 10, 12, 14 Race factories handle ONLY PLATFORM, STANDS. Their interesting objects (tippers, bridges, waterwheels) are NOT created in race mode by vtable[33] — they're loaded via the Arena Board system or are static geometry.

5. Board Constructor Mesh Pre-Loading

Each Board constructor loads specific mesh files into board+0x4xxx slots BEFORE the factory runs. The factory then reads these slots to get the mesh data needed by each object's constructor.

How It Works

// Inside LevelBoard_Dizzy_ctor (Dizzy Race, 0x41D060):
pvVar1 = operator_new(0x10D0);
pvVar1 = MeshWorld_ctor(pvVar1, App+0x174, "Levels\\Level3-WaterWheel");
*(void**)(board + 0x4BA8) = pvVar1;  // store mesh at board+0x4BA8

pvVar1 = operator_new(0x10D0);
pvVar1 = CollisionLevel_ctorWithLevel(pvVar1, board+0x4BA8);
*(void**)(board + 0x4BAC) = pvVar1;  // store collision at board+0x4BAC

The Conflict Problem

The same board+0x4xxx slot is reused for different meshes on different levels. For example:

You cannot simply "load all meshes" into board slots — you'd overwrite one mesh with another.

Solution: Just-In-Time Mesh Injection

The DLL maintains its own private array of all 46 object meshes loaded from disk. When the factory needs a specific mesh, the DLL:

1. Saves the current board slot value
2. Writes the correct mesh pointer into the slot
3. Calls the constructor (which reads the slot)
4. Restores the original board slot value

6. Object Categories: Allocating vs Static vs Configuring

All 46 verified ref types fall into three categories:

Category 1 — Allocating Objects (MULTI-INSTANCE SAFE)

The factory allocates a new object each time, calls a constructor, and appends it to the active object list (board+0x2578). Multiple instances work fine — each gets independent state. They share the pre-loaded mesh at board+0x4xxx (read-only), which is fine for rendering.

Category 2 — Static Mesh Return Objects (MULTI-INSTANCE BROKEN)

The factory does NO allocation, NO constructor, NO list append. It returns the pre-loaded mesh pointer directly. Multiple refs all point to the SAME object in memory → only one renders (at the last position set).

Category 3 — Configuring Objects

The factory doesn't create anything — it moves/reconfigures the existing mesh.

7. The Multi-Instance Problem

Root Cause

When you add two WATERWHEEL refs to a Dizzy Race MESHWORLD file:

1. Scene_CreateDynamicObjects calls vtable[33] for the first WATERWHEEL ref
2. The factory returns board+0x4BA8 (the pre-loaded mesh pointer) in local_58
3. The scene adds it to the dynamic list, sets position A, calls Init
4. Scene_CreateDynamicObjects calls vtable[33] for the second WATERWHEEL ref
5. The factory returns board+0x4BA8 again (THE SAME pointer) in local_58
6. The scene adds it to the list again, sets position B, calls Init
7. Result: Both list entries point to the same MeshWorld object. The second Init overwrites the first position. Only one renders (at position B).

The Fix: Clone-on-Return (Option A — CHOSEN)

When the universal ref-loader DLL detects a Category 2 object, it calls Level_CloneTree (0x466060) to create an independent copy before returning it.

// In the DLL factory hook, when matching WATERWHEEL/SWIRL/CHOMPER/WINDMILL/PILLAR:
void* mesh = *(void**)(board + boardOffset);  // pre-loaded mesh
void* clone = Level_CloneTree(mesh, board);     // 0x466060, thiscall
*outObj = (int)clone;                          // return the clone, not the original

Level_CloneTree (0x466060) — What It Does

undefined4* __thiscall Level_CloneTree(void* this, int param_1)
{
    // 1. Allocate new 0x10D0-byte object (same size as MeshWorld)
    undefined4* clone = operator_new(0x10D0);
    
    // 2. Call Level_ctor with parent's D3D device
    Level_ctor(clone, *(undefined4*)((int)this + 4));
    
    // 3. Set vtable to PTR_Level_DeletingDtor2 (0x4D9068)
    *clone = &PTR_Level_DeletingDtor2_004d9068;
    
    // 4. Copy parent's SceneObject (this+0x480)
    clone[0x120] = *(undefined4*)((int)this + 0x480);
    clone[0x121] = 1;  // flag: has scene object
    
    // 5. Copy parent's world matrix (this+8)
    clone[2] = *(undefined4*)((int)this + 8);
    
    // 6. Copy collision flag (this+0x430)
    *(char*)((int)clone + 0x10C) = *(char*)((int)this + 0x430);
    
    // 7. Set parent (param_1 = board)
    clone[0x11F] = param_1;
    
    // 8. Copy timer pointer (param_1 + 0x434)
    clone[0x10D] = *(undefined4*)(param_1 + 0x434);
    
    // 9. Recursively clone children (spatial tree)
    // For each child in this+0x424:
    //   Level_CloneTree(child, param_1) → append to clone's child list
    
    return clone;
}

Alternative Options (kept for reference)

Option B — Re-load from file each time:

void* mesh = operator_new(0x10D0);
MeshWorld_ctor(mesh, *(int*)(*(int*)(board + 0x878) + 0x174), "Levels\\Level3-WaterWheel");
*outObj = (int)mesh;

Slower (re-parses file) but fully independent. Works even if board slot is empty (useful for cross-level loading).

Option C — Use Stands_ctor pattern:

void* obj = operator_new(0x10D0);
Stands_ctor(obj, *(void**)(board + 0x4BA8));  // clones spatial tree from parent
*outObj = (int)obj;

This is what the game itself uses for TURRET, MACE, DRAWBRIDGE — objects that need independent instances sharing a mesh.

8. The Mesh Dependency Problem

Problem

Each Board constructor loads specific mesh files into board+0x4xxx slots. The same slot holds different meshes on different levels. The factory's constructors READ these slots to get mesh data.

If a level's constructor didn't load a mesh into the required slot, the slot is NULL. The factory does NOT null-check — it dereferences the pointer directly, causing an access violation (crash).

Solution: Just-In-Time Mesh Injection

The universal ref-loader DLL maintains a private array of all object meshes loaded from disk. When dispatching to a factory:

1. Before calling the constructor: Save the current values of all board slots the constructor will read
2. Write the correct mesh pointers from the private array into those slots
3. Call the constructor (which reads the slots)
4. Restore the original board slot values (so the level's own objects aren't broken)

Which Objects Need Which Board Slots

Objects That DON'T Need Pre-Loaded Meshes

These objects work immediately without any mesh injection:

• BONK — self-loads levels\level5-bonk via MeshWorld_ctor inside Bonk_ctor
• FAN — procedural animation, no mesh at all
• SAWBLADE — self-contained (no mesh read)
• JUDGE — no mesh read (calls Level_ctor base)
• BELL — no mesh read
• TRAPDOOR — no mesh dependency

9. The Difficulty Gate Problem

Problem

Some objects are gated behind App+0x23C != 0:

• TIPPER — only created when App+0x23C != 0
• BONK — only created when App+0x23C != 0
• BLOCKDAWG1/2 — only created when App+0x23C != 0
• GLUEBIE — only created when App+0x23C != 0
• FAN — only created when App+0x23C != 0
• SAWBLADE — only created when App+0x23C != 0

What App+0x23C Is

App+0x23C is a difficulty enum (not a simple boolean):

• 0 = Pipsqueak (easiest) — gated objects don't spawn
• 1 = Normal — gated objects spawn
• 2 = Frenzied/Hard — gated objects spawn

The absolute address is 0x4FD8B4 (App singleton at 0x4FD680 + 0x23C).

Solution

The DLL temporarily sets App+0x23C = 1 during factory dispatch for gated objects, then restores the original value afterward:

int originalDiff = *(int*)(app + 0x23C);
*(int*)(app + 0x23C) = 1;  // force Normal difficulty
// ... call factory ...
*(int*)(app + 0x23C) = originalDiff;  // restore

10. The Universal Ref Loader Design (Option B)

Overview

A bass.dll proxy that hooks the vtable[33] dispatch at 0x0040C4BA and replaces it with a universal factory that:

1. Tries all 13 Arena factories in sequence (each factory's __strnicmp will match its own refs)
2. For each factory, injects the required meshes into board slots before calling
3. For Category 2 objects (WATERWHEEL, etc.), clones the mesh instead of returning the same pointer
4. For difficulty-gated objects, temporarily sets App+0x23C = 1
5. Restores all board slots and App+0x23C after the factory returns

Hook Point

; Original at 0x0040C4BA:
call [eax + 0x84]  ; board->vtable[33](refName, &outObj, &outCol, refEntry)

; DLL patches this to:
jmp universal_factory_dispatch

Universal Factory Dispatch (Pseudocode)

void universal_factory_dispatch(
    Board* board, const char* refName, 
    void** outObj, void** outCol, RefEntry* refEntry)
{
    // 1. Try the original level's factory first
    original_factory(board, refName, outObj, outCol, refEntry);
    if (*outObj != NULL) {
        // Original factory handled it — check if it's a static-mesh return
        if (is_static_mesh_object(refName)) {
            // Clone it for multi-instance support
            *outObj = Level_CloneTree(*outObj, board);
        }
        return;
    }
    
    // 2. Original factory didn't handle it — try all other factories
    for (int i = 0; i < NUM_FACTORIES; i++) {
        FactoryFunc* factory = factories[i];
        
        // Check if this factory handles the ref name
        if (!factory_handles_ref(factory, refName))
            continue;
        
        // Get the mesh slots this factory needs
        int* slots = get_required_slots(factory);
        
        // Save original slot values
        void** saved = save_board_slots(board, slots);
        
        // Inject correct meshes
        inject_meshes(board, slots);
        
        // Handle difficulty gate
        int savedDiff = *(int*)(app + 0x23C);
        if (is_difficulty_gated(refName))
            *(int*)(app + 0x23C) = 1;
        
        // Call the factory
        factory(board, refName, outObj, outCol, refEntry);
        
        // Restore slots and difficulty
        restore_board_slots(board, slots, saved);
        *(int*)(app + 0x23C) = savedDiff;
        
        if (*outObj != NULL) {
            // Check for static-mesh return
            if (is_static_mesh_object(refName)) {
                *outObj = Level_CloneTree(*outObj, board);
            }
            return;
        }
    }
    
    // No factory handled it — return NULL (object not created)
    *outObj = NULL;
}

Private Mesh Array

At board constructor time (hooked via a separate hook), the DLL loads all 46 object meshes from disk into a private array:

struct MeshEntry {
    const char* refName;    // "WATERWHEEL", "CATAPULT", etc.
    const char* meshPath;   // "Levels\\Level3-WaterWheel", etc.
    void* mesh;              // loaded MeshWorld*
    void* collision;         // loaded CollisionLevel*
    int boardSlot;           // which board+0x4xxx slot to inject into
};

MeshEntry meshDatabase[] = {
    {"CATAPULT",    "Levels\\Level4-Catapult",    NULL, NULL, 0x5848},
    {"TIPPER",      "Levels\\Level3-Tipper",       NULL, NULL, 0x4394},
    {"WATERWHEEL",  "Levels\\Level3-WaterWheel",   NULL, NULL, 0x4BA8},
    // ... all 46 entries
};

11. Clone-on-Return for Static Mesh Objects (Option A)

Which Objects Need Cloning

Clone Implementation

// Called after the factory returns, if the ref is a Category 2 object
void* clone_static_mesh(void* originalMesh, Board* board) {
    // Level_CloneTree is at 0x466060, thiscall (ECX = originalMesh)
    // It allocates 0x10D0 bytes, copies spatial tree recursively
    typedef void* (__thiscall *CloneTreeFn)(void* this, int param_1);
    CloneTreeFn cloneTree = (CloneTreeFn)0x466060;
    return cloneTree(originalMesh, (int)board);
}

Detection Logic

bool is_static_mesh_object(const char* refName) {
    return _strnicmp(refName, "WATERWHEEL", 10) == 0
        || _strnicmp(refName, "SWIRL", 5) == 0
        || _strnicmp(refName, "CHOMPER", 7) == 0
        || _strnicmp(refName, "WINDMILL", 8) == 0
        || _strnicmp(refName, "PILLAR", 6) == 0
        || _strnicmp(refName, "BRIDGE", 6) == 0;  // base BRIDGE, not Expert
}

12. Complete Object Dependency Table

All 46 Verified Ref Types (from MESHWORLD binary parsing)

13. Complete vtable[33] Mapping

See Section 4 above for the full Race and Arena vtable[33] mapping tables.

14. Complete Board Slot → Mesh File Mapping

15. Key Function Addresses

16. Implementation Plan

Phase 1: Build the Universal Factory Hook

1. Create a bass.dll proxy that patches 0x0040C4BA with a JMP to the DLL's dispatch function
2. The dispatch function intercepts the factory call and tries all 13 Arena factories
3. For each factory attempt, save/restore board slots and inject meshes

Phase 2: Just-In-Time Mesh Injection

1. Build a mesh database mapping all 46 ref names → mesh file paths + board slot offsets
2. At board constructor time, load all meshes from disk into a private array
3. During factory dispatch, inject the correct mesh into the board slot before calling the constructor

Phase 3: Clone-on-Return for Static Mesh Objects

1. Detect Category 2 objects (WATERWHEEL, SWIRL, CHOMPER, WINDMILL, PILLAR, BRIDGE-base)
2. After the factory returns a static mesh pointer, call Level_CloneTree (0x466060) to clone it
3. Return the clone instead of the original

Phase 4: Difficulty Gate Bypass

1. Detect difficulty-gated objects (TIPPER, BONK, BLOCKDAWG, GLUEBIE, FAN, SAWBLADE)
2. Before calling the factory, save App+0x23C and set it to 1
3. After the factory returns, restore App+0x23C

Phase 5: Crash Test

1. Compile with MinGW: i686-w64-mingw32-gcc -shared -o bass.dll mod.c -lwinmm -Wl,--enable-stdcall-fixup -O2 -static -static-libgcc -Wl,--add-stdcall-alias
2. Crash test via hbtestd or Wine/Xvfb: launch game, wait 35s, check if process alive
3. Copy to mods/universal-ref-loader/ with README

17. Build & Test

Build Command

i686-w64-mingw32-gcc -shared -o bass.dll universal_ref_loader.c \
    -lwinmm -Wl,--enable-stdcall-fixup -O2 -static -static-libgcc \
    -Wl,--add-stdcall-alias

Crash Test

# Via hbtestd MCP (preferred):
mcp_hbtestd_test_dll_mod(path="universal_ref_loader.zip", target_dll="bass.dll", timeout=10)

# Via Wine/Xvfb:
DISPLAY=:99 LIBGL_ALWAYS_SOFTWARE=1 timeout 35 wine Hamsterball.exe
# Check if process is alive after 35s (catches stack corruption, wrong hook addresses)

Deliverables

• mods/universal-ref-loader/bass.dll — compiled DLL
• mods/universal-ref-loader/universal_ref_loader.c — source code
• mods/universal-ref-loader/README.md — documentation
• mods/universal-ref-loader/hamsterball-universal-ref-loader.zip — packaged mod
• Update mods/README.md catalog

Appendix: Existing Related Files

🔗 Related Documents

• Level Object Factory
• MESHWORLD File Format & Object

📂 View source on GitHub

Universal Ref Loader — Hamsterball DLL Mod v3

What It Does

This mod patches the game's level-object dispatch system to allow any object ref to be loaded into any level. Normally, each level only loads refs that its own Board vtable[33] factory recognizes (e.g. SpeedCylinder only in Up levels, Bonk only in Expert/Master levels, Gears only in Impossible level).

The mod hooks the vtable[33] dispatch at 0x0040C4BA (inside Scene_CreateDynamicObjects at 0x40C430) and replaces it with a universal factory that:

1. Tries the original factory first — preserves normal behavior for all existing refs
2. Falls through to all 13 Arena factories if the original didn't handle the ref
3. JIT mesh injection — if a factory needs a board mesh slot that's NULL (not loaded by the current level), loads the mesh from disk on the fly
4. Clones static-mesh objects (WATERWHEEL, SWIRL, BRIDGE-base) via Level_CloneTree for multi-instance support
5. Bypasses difficulty gates — temporarily sets App+0x23C = 1 (Normal) for gated objects (TIPPER, BONK, BLOCKDAWG, GLUEBIE, FAN, SAWBLADE, MACE)
6. Safety checks board slots — skips factories whose required mesh slots can't be filled (prevents crashes)

How to Use

1. Rename original bass.dll to bass_real.dll (for audio passthrough)
2. Copy this mod's bass.dll to your Hamsterball game directory
3. Add ref names to MESHWORLD Section 1 in any level file
4. The mod will try all Arena factories to create the object, loading meshes from disk as needed

JIT Mesh Injection

When a factory reads a board+0x4xxx slot that's NULL (because the current level's Board constructor didn't load that mesh), the mod:

1. Looks up the board offset in the mesh database (maps offsets → file paths)
2. Calls MeshWorld_ctor(mem, d3dDevice, path) to load the mesh from disk
3. Optionally calls CollisionLevel_ctorWithLevel(mem, mesh) for collision
4. Writes the loaded mesh pointer into the board slot
5. Calls the factory (which reads the slot)
6. Restores the original NULL value after the factory returns

Meshes are cached so each file is only loaded once per session.

Mesh Database (verified from decompiled board constructors)

Verified Features

Static-Mesh Cloning

Objects like WATERWHEEL and SWIRL return the same board slot pointer for every ref — only one instance renders. This mod calls Level_CloneTree to create independent copies:

Factory Dispatch Order

Factories are tried in order of inclusiveness (most ref types first):

1. Expert — BONK, FAN, SAWBLADE, BRIDGE, JUDGE, BELL (no mesh deps, self-loading)
2. Wobbly — SMASHER1, SMASHER2 (configuring only)
3. Master — BRIDGE, TIPPER, BONK, BBRIDGE1-2, POPCYLINDER, BLOCKDAWG1-2, CATAPULT, GLUEBIE
4. Tower — CATAPULT, MACE, DRAWBRIDGE, WINDMILL, TRAPDOOR, CHOMPER, TURRET
5. Impossible — LOOPER, GEAR, BIGGEAR, ROTATOR, PENDULUM
6. Up — LIFTER, SPEEDCYLINDER, TIMEBUTTON
7. Dizzy — TIPPER, WATERWHEEL, SWIRL, GLUEBIE
8. Beginner — BRIDGE (base)
9. Neon, Odd, Toob, Glass, Sky — level-specific objects

Limitations

• WINDMILL: Returns static mesh + creates CollisionLevel with attach — not cloned yet (complex multi-object creation).
• N:/E: prefixed refs: Handled by the original factory's N:/E: handler, not by the universal dispatch.
• Slot ambiguity: Some board offsets map to different mesh files on different levels (e.g. 0x436C = Tipper on Dizzy but Catapult on Tower). The mesh DB tries all entries; the first that loads successfully is used.

Build

i686-w64-mingw32-gcc -shared -o bass.dll universal_ref_loader.c \
  -lwinmm -Wl,--enable-stdcall-fixup -O2 -static -static-libgcc \
  -Wl,--add-stdcall-alias

Technical Details

• Hook point: 0x0040C4BA (CALL [EAX+0x84] → CALL universal_factory + NOP)
• Calling convention: __thiscall (ECX=board), 4 stack args
• JIT mesh loading: MeshWorld_ctor (0x461510) + CollisionLevel_ctorWithLevel (0x465080)
• D3D device: *(board+0x878) + 0x174 (App+0x174)
• BASS proxy: v3 lazy loader pattern (LoadLibraryA on first BASS call, not in DllMain)
• All addresses verified via GhidraMCP decompilation + vtable memory reads (June 2026)

See docs/UNIVERSAL_REF_LOADER_DESIGN.md for the complete reverse engineering analysis.

🔗 Related Documents

• Global Lifter (DropLift) Spawn
• Universal Ref Loader

📂 View source on GitHub

Reverse Engineering Playbook

A program-agnostic guide for analyzing compiled binaries. The Hamsterball project is used as a running example, but the methodology applies to any compiled program (games, applications, malware, firmware).

Quick Start

Running Example

Throughout this playbook, Hamsterball.exe (PE32, MSVC 2003, D3D8 + DInput8 + BASS) illustrates each step. See the case study for the full project-specific details.

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

Ball Object — Complete Modder's Reference

Verified via direct Ghidra decompilation of Hamsterball.exe (Athena engine, PE32 i386).
All offsets below were extracted from the live decompiled code via the GhidraMCP headless server.
This document replaces / supplements BALL_OBJECT.md with authoritative, source-verified data.

Quick Stats

Table of Contents

1. Position & Velocity
2. Ball-Related Functions (Complete List)
3. What You Can Do With the [[39040799821588|ball object]]
4. Modding Recipes
5. Verified Memory Layout (Key Fields)

Position & Velocity

Verified by Ghidra decompilation of Ball_ctor2 (0x004039E0)

// Ball_ctor2 initializes these fields to zero:
*(undefined4 *)((int)this + 0x164) = 0;   // pos_x
*(undefined4 *)((int)this + 0x168) = 0;   // pos_y
*(undefined4 *)((int)this + 0x16c) = 0;   // pos_z
*(undefined4 *)((int)this + 0x170) = 0;   // vel_x ← **VERIFIED**
*(undefined4 *)((int)this + 0x174) = 0;   // vel_y ← **VERIFIED**
*(undefined4 *)((int)this + 0x178) = 0;   // vel_z ← **VERIFIED**

Verified by Ball_ApplyForceWithMultipliers (0x00402650)

// Accumulates directional force into velocity:
*(float *)((int)this + 0x170) = param_1 * param_4 + *(float *)((int)this + 0x170);
*(float *)((int)this + 0x174) = param_2 * param_4 + *(float *)((int)this + 0x174);
*(float *)((int)this + 0x178) = param_3 * param_4 + *(float *)((int)this + 0x178);

Verified by Ball_ApplyForceV2 (0x004016F0)

Same pattern — writes to +0x170/174/178 with identical guards.

Layout check (no gaps, no overlaps)

0x164  float  pos_x
0x168  float  pos_y
0x16C  float  pos_z
0x170  float  vel_x  ← confirmed
0x174  float  vel_y  ← confirmed
0x178  float  vel_z  ← confirmed
0x17C  float  accel_x
0x180  float  accel_y
0x184  float  accel_z
0x188  float  max_speed

✅ The velocity offsets are definitively correct.

Ball-Related Functions

Core Lifecycle

Physics & Movement

State Changes

Rendering

Input

Misc

What You Can Do With the Ball Object

1. Read/Write Velocity (Instant Boosts)

// Direct velocity manipulation — bypasses all engine multipliers
float* ball = (float*)ball_ptr;
ball[0x170/4] = 5000.0f;  // X velocity
ball[0x174/4] = 0.0f;     // Y velocity
ball[0x178/4] = 0.0f;     // Z velocity

Verified source: Ball_ApplyForceWithMultipliers @ 0x00402650 reads/writes these exact offsets.

2. Read/Write Position (Teleport)

ball[0x164/4] = 100.0f;   // X position
ball[0x168/4] = 50.0f;    // Y position
ball[0x16c/4] = 200.0f;   // Z position

Note: Also set teleport field at +0xC3C to prevent physics from overriding it on the next frame.

3. Change Ball Radius

// Ball_Shrink sets radius = 13.0f (0x41500000)
// Ball_Grow sets radius = 26.0f (0x41D00000)
// Normal radius = 27.0f (0x41D80000) — set in Ball_ctor2
*(float*)(ball + 0x284) = 50.0f;  // Giant ball

4. Change Max Speed

// Ball_ctor2 default: 0x459C4000 (~5000.0f)
// Ball_Shrink: 0x40200000 (2.5f)
// Ball_Grow: 0x40A00000 (5.0f)
*(float*)(ball + 0x188) = 10000.0f;  // Super speed

5. Force Death-Fall State

Ball_Shrink(ball_ptr);  // @ 0x00402200
// Sets: +0xC4C = 1 (is_shrunk), radius=13.0, max_speed=2.5, plays sound

6. Force Split Power-Up

Ball_Shatter(ball_ptr, some_param);  // @ 0x00408D70
// Guard: checks *(char*)(ball + 0x324) == 0 (not already split)

7. Apply Launch Pad Boost

// First set trajectory vector on physics body:
*(float*)(*(int*)(ball + 0x1A4) + 0xCA4) = dir_x;
*(float*)(*(int*)(ball + 0x1A4) + 0xCA8) = dir_y;
*(float*)(*(int*)(ball + 0x1A4) + 0xCAC) = dir_z;
Ball_ApplyTrajectory(ball);  // @ 0x00403750
// Damps Y by 0.7x, normalizes, scales by 0.01, sets impact block = 100 frames

8. Change Gravity Plane

Ball_SetTiltedGravity(ball);  // Normal = (0, -1, 0)  @ 0x00403100
Ball_SetFlatGravity(ball);    // Normal = (0, 0, 1)     @ 0x00403150
Ball_ResetCollisionMesh(ball); // Reset orientation        @ 0x004030B0

9. Check If Ball Is Falling

char is_shrunk = *(char*)(ball + 0xC4C);
// Set by Ball_Shrink (→1), cleared by Ball_Grow (→0)

10. Read Ball Speed Scale

float speed_scale = *(float*)(ball + 0x18C);  // default 1.0f
// Affects all velocity calculations in Ball_Update

11. Read Player Index

int player_idx = *(int*)(ball + 0x18);
// -1 = no player (AI / demo), 0-3 = human player index

Modding Recipes

Recipe 1: Permanent Super Speed

Hook Ball_ctor2 (0x004039E0), after the line:

*(undefined4 *)((int)this + 0x188) = 0x459c4000;  // max_speed = 5000

Change 0x459c4000 to 0x461C4000 (10000.0f).

Recipe 2: Giant Ball Mode

In your mod DLL, every frame after Ball_Update returns:

*(float*)(ball + 0x284) = 100.0f;  // radius

The collision mesh (at ball + 0x1A4) must also be scaled — call CollisionMesh_SetRadius or patch the mesh directly.

Recipe 3: Zero-Gravity Mode

Patch Ball_Update to skip gravity accumulation. The gravity vector is at +0x1A8 (default 0, 1.0, 0).

*(float*)(ball + 0x1A8) = 0.0f;  // gravity_x
*(float*)(ball + 0x1AC) = 0.0f;  // gravity_y
*(float*)(ball + 0x1B0) = 0.0f;  // gravity_z

Recipe 4: Invincibility (No Death-Fall)

Hook Ball_Shrink (0x00402200) to return immediately:

xor eax, eax
retn 4

Recipe 5: Always-Split Power-Up

Hook the guard check in Ball_Shatter (0x00408D70):

; NOP out the "if (*(char*)(this+0x324) == 0)" check
nop
nop
nop
nop
nop
nop

Verified Memory Layout (Key Fields)

Extracted directly from Ball_ctor2 decompilation @ 0x004039E0:

How to Use This Document

1. Attach a debugger (Cheat Engine, x64dbg) to Hamsterball.exe.
2. Find the Ball pointer: In Ball_Update (0x00405E00), the first argument in ECX is this.
3. Read/write fields using the offsets above.
4. Hook functions by patching the vtable at 0x004CF3A0 or placing JMP hooks at the function addresses.

Sources

All data verified via live GhidraMCP headless decompilation (http://127.0.0.1:8089/decompile_function) on Hamsterball.exe:

• Ball_ctor2 @ 0x004039E0 — struct layout, initial values
• Ball_ApplyForceWithMultipliers @ 0x00402650 — velocity write pattern
• Ball_ApplyForceV2 @ 0x004016F0 — velocity write pattern (alt)
• Ball_Shrink @ 0x002200 — odd race shrink state (E:SHRINK)
• Ball_Grow @ 0x00402270 — odd race grow recovery (E:GROW)
• Ball_Update @ 0x00405E00 — main physics tick overview
• Ball_Shatter @ 0x00408D70 — arena 8-ball split mechanic (called from FollowBall_Update)
• Ball_GetInputForce @ 0x0046EC30 — input system integration
• Ball_SetTrajectory / Ball_ApplyTrajectory — launch pad mechanics

Document generated: 2026-06-05
Method: Ghidra decompilation + cross-reference with ball_struct.h
Confidence: High — all offsets verified against primary source code

🔗 Related Documents

• Odd Race
• Custom Event Plane Implementat

📂 View source on GitHub

Audio System — Deep Documentation

Architecture Overview

Hamsterball uses a dual-API audio system:

1. BASS library (un4seen.com) — music playback (.mo3/.xm/.it tracker modules)
2. DirectSound8 — sound effects with 3D positional audio

Both systems are managed through the SoundDevice object stored at App+0x178 (offset 0x84C from SoundDevice's App pointer).

SoundDevice Structure

The SoundDevice (vtable at 0x4D911C) is the central audio manager:

Sound Loading Pipeline

Entry Point: Sound_LoadOggOrWav (0x459660)

Sound_LoadOggOrWav(filename):
  1. Try "%s.ogg" — check file access
  2. If .ogg exists → Sound_LoadOgg()
  3. Else try "%s.wav" — check file access
  4. If .wav exists → SoundList_LoadWAV()

The game prefers OGG Vorbis over WAV, always trying .ogg first.

SoundList_LoadWAV (0x458F40)

Manual WAV file parser — does NOT use DirectSound helpers:

1. Open file, read entire contents into memory
2. Validate "RIFF" + "WAVE" headers (4-char string compare)
3. Parse WAV format chunks: sample rate, channels, bits per sample
4. Scan for "data" chunk by iterating through file
5. Create IDirectSound8 buffer (WAVEFORMATEX + DSBUFFERDESC):
   • DSBUFFERDESC.dwSize = 0x24
   • DSBUFFERDESC.dwFlags = 0x82 (DSBCAPS_STATIC | DSBCAPS_CTRLVOLUME)
   • DSBUFFERDESC.dwBufferBytes = data_chunk_size
6. Lock buffer (DSLock), copy PCM data, unlock
7. Create SoundEntry (12 bytes: vtable + App* + buffer_handle) per DirectSound buffer
8. Append to SoundList's AthenaList
9. For multi-buffer sounds (streaming): create additional buffers with duplicate entries

Sound_LoadOgg (0x459310)

1. Open .ogg file with CRT_fsopen("rb")
2. Parse OGG Vorbis headers (channels, sample rate, bits)
3. Compute buffer size: channels × bits/8 × sample_count
4. Create IDirectSound8 buffer with computed format
5. Decode OGG stream into DirectSound buffer (read loop)
6. Create SoundEntry entries, append to AthenaList
7. For multi-buffer sounds: duplicate entries for streaming segments

SoundEntry Structure (12 bytes)

Sound Playback Pipeline

Channel Management

Sound_GetNextChannel (0x459810) — Circular allocator:

Sound_GetNextChannel(SoundList):
  index = list.next_index
  if index < list.count:
    entry = list.entries[index]
    list.next_index = index + 1
    if entry != NULL: return entry
  // Wrap around
  list.next_index = 0
  if list.count > 0:
    return list.entries[0]
  return 0

3D Positional Audio

Sound_CalculateDistanceAttenuation (0x466750):

Sound_CalculateDistanceAttenuation(this, x, y, z) → float (0.0-1.0):
  // Find nearest listener
  best_dist = FLT_MAX
  for each listener in this.listeners:
    dist = sqrt((x-lx)² + (y-ly)² + (z-lz)²)
    if dist < best_dist: best_dist = dist
  
  // Linear rolloff between min and max distances
  if best_dist <= this.min_rolloff:
    return 1.0  // Full volume
  elif best_dist >= this.max_rolloff:
    return 0.0  // Silent
  else:
    range = max_rolloff - min_rolloff
    if range == 0.0: range = 1.0  // Avoid divide-by-zero
    return 1.0 - (best_dist - min_rolloff) / range

Key constants:

• _DAT_004d9120 = FLT_MAX (initial distance for comparison)
• _DAT_004cf368 = 0.0 (zero/silence)
• _DAT_004cf310 = 1.0 (full volume)

Sound_Play3D (0x459860):

Sound_Play3D(this, x, y, z):
  Sound_CalculateDistanceAttenuation(this->device, x, y, z)
  Sound_PlayChannel(this)

Sound_PlayChannel (0x4597B0):

Sound_PlayChannel(SoundList):
  if !app || !device || volume == 0.0: return
  // Get next channel from circular list
  channel = next_entry_from_list
  if channel: Sound_StartSample(channel)
  else: wrap to beginning, try first entry

Sound_StartSample (0x4595B0):

Sound_StartSample(entry):
  if entry->app->sound_enabled:
    Reset sample via vtable(+0x48)       // IDirectSoundBuffer::SetCurrentPosition(0)
    Set volume via vtable(+0x3C)         // IDirectSoundBuffer::SetVolume(clamped)
    Play via vtable(+0x30, 0, 0, 0)     // IDirectSoundBuffer::Play(0, 0, 0)

Sound_InitChannels (0x434580)

Used during game object initialization (e.g. sawblades):

Sound_InitChannels(this, randomize_pitch):
  this.sound_flag = 0
  this.channel_1 = Sound_GetNextChannel(this->app->sound_ids_0x4AC)
  this.channel_2 = Sound_GetNextChannel(this->app->sound_ids_0x4B0)
  if channel_1: Sound_StartSample(channel_1)
  this.pitch = 0x140 (320 decimal = base pitch/frequency)
  if channel_2: Sound_Play3DAtPosition(channel_2)
  if channel_1: Sound_Play3DAtPosition(channel_1)
  if randomize_pitch:
    this.float_pitch = RNG_Rand(0, 25)  // Random 0-25
  this.sound_playing = 0

Music System (BASS)

MusicPlayer Structure

LoadMusicFile (0x46A020)

LoadMusicFile(this, filepath):
  strcpy(this+0x424, filepath)
  handle = BASS_MusicLoad(0, filepath, 0, 0, BASS_MUSIC_PRESCAN, 0)
  this->handle = handle
  if handle != 0:
    return (1 << 24) | handle  // Success
  else:
    BASS_ErrorGetCode()
    Window_Notify("Music Initialization Error: %s")
    return 0

BASS_MusicLoad flags: 4 = BASS_MUSIC_PRESCAN (pre-scan for accurate length/sync)

LoadJukebox (0x46A4D0)

Parses jukebox.xml for song definitions:

LoadJukebox(filename):
  FileHandle_Open(filename)
  while tag = MWParser_ReadTag():
    if tag.name == "SONG":
      name = ""
      hex_id = 0
      while inner_tag = MWParser_ReadTag():
        if inner_tag.name == "NAME": name = inner_tag.value
        if inner_tag.name == "HEX": hex_id = sscanf(value, "%x")
      RegKeyList_AppendStr(name, hex_id)

Example jukebox.xml:

<SONG>
  <NAME>music_mo3</NAME>
  <HEX>1A</HEX>
</SONG>

Audio_StopChannel (0x46A0D0)

Audio_StopChannel(music_player):
  BASS_ChannelStop(music_player->handle)

Music Channels (App Offsets)

Sound Volume Management

Level_ReadSoundVolume (0x466570)

Level_ReadSoundVolume(SoundDevice):
  RegKey_Open(app->registry)
  if RegKey_ReadString("Sound Volume") exists:
    volume = Registry_ReadFloat("Sound Volume")
    device->volume = volume
  else:
    device->volume = 1.0  // 0x3F800000
  RegKey_Close()

SoundDevice_dtor (0x4668A0)

On destruction:

1. Save volume to registry: RegKey_WriteDWORD("Sound Volume", device->volume)
2. Iterate and delete all SoundEntry objects (AthenaList at +0x4)
3. Iterate and free secondary buffer list (AthenaList at +0x41C)
4. Release IDirectSound8 interface (COM Release at vtable+8)
5. Free listener position arrays (Vec3List_Free)

3D Listener System

The 3D listener array enables per-ball positional audio in multiplayer:

• Listener count at SoundDevice+0x850
• Each listener is a Vec3 (12 bytes: X, Y, Z) starting at SoundDevice+0x854
• Updated per-ball in Ball_Update Phase 17 (multiplayer sync)
• Ball positions are the listener positions for distance calculations

Sound Events During Gameplay

Ball_Update Phases

Collision Event Sounds

Key Address Map

Reimplementation Notes (SDL2/SDL_mixer or OpenAL)

Replacement Strategy

• BASS → SDL_mixer: Load .mo3/.xm/.it via SDL_mixer with mikmod/timidity
• DirectSound8 → SDL_mixer: Use SDL_mixer channels (Mix_Chunk/Mix_Music)
• Alternative: OpenAL for true 3D positional audio with proper distance model

Key Differences

1. Channel allocation: SDL_mixer has built-in channel management (Mix_GroupChannel), similar to circular allocator pattern
2. 3D audio: SDL_mixer lacks native 3D — approximate with pan/volume or use OpenAL
3. OGG/WAV loading: Both natively supported by SDL_mixer (Mix_LoadWAV_RW)
4. Volume control: SDL_mixer uses 0-128 scale; DirectSound uses dB attenuation
5. Music format: .mo3 tracker modules need mikmod/timidity — SDL_mixer supports these natively

Recommended Architecture

// Audio system (SDL_mixer + OpenAL for 3D)
class SoundDevice {
    std::vector<SoundEntry> entries;
    float volume;           // 0.0-1.0
    float min_rolloff;      // 3D min distance
    float max_rolloff;      // 3D max distance
    std::vector<Vec3> listeners;  // Per-ball positions
    
    SoundEntry* LoadOggOrWav(const char* filename);
    void Play3D(SoundEntry* entry, Vec3 position);
    float CalculateDistanceAttenuation(Vec3 position);
};

class MusicPlayer {
    Mix_Music* handle;
    std::string filepath;
    
    uint32_t LoadMusicFile(const char* filepath);
    void Stop();
};

🔗 Related Documents

• Save & Registry System
• Input System

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/mods/half_size_all/README.md)

half_size_all

Shrinks the player's ball to half size by inlining Ball_Shrink's physics fields

How It Works

Hooks Scene_SpawnBallsAndObjects at the point where the player ball has just been created and registered. A code cave checks if the ball's player index (ball+0x18) is 0, and if so, writes the same three fields that Ball_Shrink (0x00402200) sets — but without calling the function, so no sound effect plays.

Fields written (identical to Ball_Shrink):

Only player index 0 is affected. AI balls, split balls, follow balls, and board-init balls remain normal size.

Hook Details

The code cave:

1. CMP dword [ESI+0x18], 0 — is this player 0?
2. If no → skip to step 4
3. If yes → write radius=13.0, physics_scale=2.5, unused_init_flag=1 (NOTE: this flag is DEAD code — never read by any function, but we set it anyway to match original behavior)
4. Execute original MOV byte [ESI+0x281], 0
5. JMP back to 0x0041C8DE

Files

• half_size_balls.c — C source code
• bass.dll — Compiled DLL (PE32 i386)
• half_size_balls.zip — Packaged zip

Proxy Type

BASS.dll proxy. Installation:

1. Rename original bass.dll → bass_real.dll in the Hamsterball game folder
2. Copy the mod's bass.dll into the game folder
3. Launch Hamsterball

A Hamsterball_half_size.log file is written next to the EXE showing whether the hook applied.

🔗 Related Documents

• half_size_all
• Odd Race

📂 View source on GitHub

Hamsterball — Global Variables and Data Constants

What This Document Is

A reverse-engineering reference for modders and researchers listing global variables and data constants found in Hamsterball.exe. These are symbols that live in the .data or .rdata sections of the PE image and are accessed by the game code through DAT_xxxxxx references, named labels, or inline constants.

Why This Matters for Modding

Many game behaviors are controlled not by function logic but by scalar constants in .data:

• Ball physics multipliers (speed, gravity, friction)
• Camera orbit distance and damping
• Damage/touch force values
• RNG range constants
• Vtable pointers used for dynamic dispatch

If you patch these values in memory or replace them at image load time, you can drastically change game behavior without changing a single instruction.

Table of Contents

1. Confirmed Named Globals (via Ghidra renames)
2. Game Constants .data / .rdata (0x004C0000–0x00534...)
3. Vtables and Jumps in the Data Section
4. Named Data Constants with Context
5. Float Constants (0x004CF000–0x004D0500)
6. String Table Addresses in .rdata
7. How to Patch Constants at Runtime
8. Recommended Modding Recipes
9. Address Quick Reference
10. Verification Methodology

Confirmed Named Globals

These have been manually renamed in Ghidra and are confirmed by the renames_backup.json (restored at session start).

Floating-Point Constants (0x004CF000–0x004D0500)

The engine keeps many scalar constants in the .data section. They are NOT loaded as immediate values into instructions; they are loaded as memory references (_DAT_004CFxxx). This makes them trivial to patch from external code.

Core Ball Physics Constants

Modding Recipes — Physics

1. Super Ball Mode — set 0x004CF380 (hit recovery) to 1.0f:
   The ball no longer loses momentum when hit by hazards.
2. Ice Mode — set 0x004CF3F0 (damping) to 1.0f:
   Ball never slows down from friction/gravity. Will fly off levels.
3. Dizzy Immunity — set 0x004CF378 to 1.0f:
   When the +0x324 dizzy flag is set, force is not reduced.
4. Heavy Steel Ball — set 0x004CF3E8 to 0.1f:
   Angular velocity barely changes; ball rolls slowly.

Camera / Orbit Constants

Modding Recipes — Camera

1. Far Orbit — change 0x004CFF78 from 700.0f to 1200.0f:
   Camera can zoom much farther from the ball.
2. Wave-Cam Disable — set 0x004D03A4 to 0.0f:
   Camera sine-wave bob disappears — perfectly smooth follow.

Collision / Touch Damage Constants

Modding Recipes — Collision

1. Hazard Immunity — raise 0x004CF484 to 99999.0f:
   Collision check never succeeds → hazards never touch you.
2. Spawn Offset Fix — set 0x004D0434 to 0.0f:
   Ball spawns exactly at START.y instead of floating above.

RNG / Math Constants

Graphics / Rendering Constants

Movement / Input Constants

Vtables and Jumps

These are pointers to vtable arrays or function pointer tables stored in .data.

String Table Addresses in .rdata

The binary embeds strings at fixed addresses in the .rdata section. Some are used as global identifiers passed to functions.

How to Patch Constants at Runtime

Method 1 — External DLL

// In your mod DLL (injected into Hamsterball.exe process)
#define ADDR_HIT_RECOVERY      ((float*)0x004CF380)
#define ADDR_DAMPING           ((float*)0x004CF3F0)

void __declspec(dllexport) ApplyMods() {
    // Make the pages writable
    DWORD oldProtect;
    VirtualProtect(ADDR_HIT_RECOVERY, sizeof(float), PAGE_READWRITE, &oldProtect);

    // Patch values
    *ADDR_HIT_RECOVERY = 1.0f;   // Never reduce force on hit
    *ADDR_DAMPING      = 0.999f; // Very slippery ball

    VirtualProtect(ADDR_HIT_RECOVERY, sizeof(float), oldProtect, &oldProtect);
}

Method 2 — Cheat Engine

1. Open Cheat Engine, attach to Hamsterball.exe
2. Add Address Manually → enter 004CF3F0 as float
3. Freeze value at 1.0f → instant zero-friction mode

Method 3 — DLL Injection at Load Time

Use detours, MinHook, or a manual IAT hook. Patch .data section before WinMain runs so the game never sees the original values.

Recommended Modding Recipes

1. God Mode (Hazard Immunity)

*(float*)0x004CF484 = 99999.0f;  // Distance threshold

2. Super Speed

*(float*)0x004CF3F0 = 1.0f;   // No friction damping
*(float*)0x004CF310 = 5.0f;   // Max backward speed

3. Dizzy Immunity

*(float*)0x004CF378 = 1.0f;   // Dizzy flag no longer reduces force

4. Smooth Camera

*(float*)0x004D03A4 = 0.0f;   // Wave_Sin scale → no bob
*(float*)0x004CFF78 = 2000.0f; // Far max orbit

5. Spawn Height Fix

*(float*)0x004D0434 = 0.0f;   // No offset above START marker

Address Quick Reference

0x004CF308    Depth bias (shadow decal)
0x004CF310    Max movement multiplier (1.0f)
0x004CF368    Zero float (0.0f)
0x004CF36C    Speed boost / power-down mult
0x004CF370    Collision deflection dir multiplier
0x004CF374    Momentum-transfer mult
0x004CF378    Dizzy state force mult
0x004CF380    Hit recovery force mult
0x004CF3C8    UV V-inversion (1.0f)
0x004CF3E8    Angular velocity scale (1.0f)
0x004CF3EC    Camera MIN_DIST
0x004CF3F0    Gravity / damping (0.95f)
0x004CF41C    Light range scale
0x004CF454    Shininess multiplier
0x004CF484   Collision dist threshold
0x004CF48C   AI tick accumulator (~0.05)
0x004CF508   AI activation distance ratio
0x004CF550   AI flee distance
0x004CF554   Angle lower bound (0.0)
0x004CF558   Angle wrap (360.0)
0x004CFF78   Camera MAX_DIST (700.0)
0x004D0250   Forward half-speed (~0.5)
0x004D03A0   Camera wave amplitude
0x004D03A4   Camera wave scale
0x004D0418   180/PI rad→deg
0x004D0434   Spawn vertical offset
0x004D2334   s_BACK (UI string)
0x004D48A0   Save header string
0x004D9120   Huge float sentinel
0x004D9CDC   MeshWorld_vtable
0x004D9E54   MESHWORLD tokenizer string table
0x004F7360   PTR_OBJ_VTABLE (193 xrefs)
0x004FD680   g_App (global App* pointer)
0x005341CC   g_renderIndex

Verification Methodology

All addresses in this document were derived from:

1. Ghidra decompilation (analysis/ghidra/decompilations/) — raw _DAT_004xxxxx references in .c files
2. Ghidra renames_backup.json — manually renamed global labels
3. GhidraMCP list_globals — live project query of labeled data
4. Cross-reference count from Ghidra xrefs — values with ≥3 xrefs are high-confidence

What was NOT verified

• Exact float values at each address (Ghidra shows _DAT_ names but not the literal in decompilation). Where exact values are given, they are inferred from context (e.g., * 0.95f comment near 0x004CF3F0). To get ground-truth values, read 4 bytes at the VA in the running process.
• Values may change between game versions. This document targets the version analyzed (Hamsterball.exe MD5 from docs/APP_OBJECT.md).

Document Revision

• Compiled from: Ghidra project, renames_backup.json, raw decompilations
• Coverage: 24 unique DAT_004xxxxx references extracted from raw .c files + 5 named globals
• Next additions: Runtime memory dump verification (read actual float/int values at each VA), more vtable addresses, additional string table bases

For object-level offsets (App, Ball, Scene structs), see APP_OBJECT.md, BALL_OBJECT_MODDING.md, and SCENE_STRUCT.md.

🔗 Related Documents

• Options Menu
• Arena Scoring System

📂 View source on GitHub

8-Ball Spawn Mod

Press B during gameplay to spawn an 8-ball in front of your hamster ball. The 8-ball spawns with physics and rolls/collides just like the balls in Rodent Rumble arenas.

What's New

• Audio forwarding: All 10 BASS functions the game imports are forwarded to bass_real.dll. The game now has full audio while the mod is active.
• Single-ball overwrite: Only one 8-ball can exist at a time. Pressing B again repositions the existing 8-ball to your current location and velocity — no new ball is created.
• Dead AI fields documented: CHASE/HOME/SPINDISTANCE values are set but have no effect because is_8ball (ball+0xC74) is never set to 1. The ball is a physics-only debris ball.

Installation

1. In your Hamsterball game folder, rename bass.dll → bass_real.dll
2. Copy the mod's bass.dll into the game folder
3. (Optional) Copy 8ball_spawn.ini next to bass.dll for configuration
4. Launch the game, enter a level or arena, press B to spawn an 8-ball

How It Works

The 8Ball mesh is preloaded by the game's resource loader into the board mesh array at board+0x268 (index 9 of the array at board+0x244). The ball mesh index field ball+0x754 controls which mesh the ball uses — setting it to 9 makes the ball render as the 8-ball.

Ball creation follows the same pattern as CreateBadBall (0x40BCA0):

1. operator_new(0xC98) allocates ball memory
2. Ball_ctor(mem, scene) constructs the ball
3. vtable[1]() initializes physics defaults
4. Position is set in front of the player's ball
5. ball+0x754 = 9 selects the 8Ball mesh
6. ball+0x18 = -1 sets player_index to none (debris ball)
7. Player's exact velocity vector is copied (same direction and speed)
8. Radius stays at Ball_InitPhysicsDefaults default (35.0)
9. Ball is added to scene+0x29D4 (bad_balls_list) and scene+0x2DEC (all_balls_list)

Single-Ball Overwrite

If a previously spawned 8-ball is still valid (vtable check against 0x4CF3A0), pressing B again repositions it to the new spawn location with the player's current velocity. No new allocation is made — the same ball object is reused. If the old ball has been freed or corrupted, a fresh ball is allocated.

Audio Forwarding

The mod loads bass_real.dll on the first BASS function call (not in DllMain, to avoid loader lock deadlocks on real Windows). All 10 functions the game imports are forwarded with correct __stdcall calling conventions:

If bass_real.dll is not found, all functions return success values (1/0) — the game runs without audio but does not crash.

AI Fields (Dead Code)

The mod sets CHASE=100000, HOME=100000, SPINDISTANCE=1.0 on the spawned ball. However, these fields have no effect because:

• ball+0xC74 (is_8ball flag) is never set to 1
• Without that flag, Ball_Update (0x408390) skips the AI chase block entirely via if (ball[0x31d] != 0 || scene[0x237] != 0)
• The ball behaves as a physics-only debris ball — it rolls, falls, and collides but never actively chases other balls

To enable AI behavior, ball+0xC74 would need to be set to 1. This would make the 8-ball chase the nearest player using the CHASE/HOME/SPINDISTANCE parameters.

Configuration

Edit 8ball_spawn.ini (placed next to bass.dll):

[8ball]
spawn_key=0x42       ; B key (default). See VK_* constants on MSDN
spawn_distance=40    ; Distance in front of player

Build

i686-w64-mingw32-gcc -shared -o bass.dll 8ball_spawn.c \
    -lwinmm -Wl,--enable-stdcall-fixup \
    -O2 -static -static-libgcc -Wl,--add-stdcall-alias

Files

Technical Notes

• BASS_SetConfig/BASS_GetConfig are now forwarded to bass_real.dll (previously stubbed). The game calls BASS_SetConfig via SEH-protected code — forwarding with correct __stdcall convention works safely.
• Scene/Board discovery uses brute-force App struct scan for the Scene vtable (0x4D0260), same approach as the player_clones mod.
• The 8-ball has no AI — it spawns as a physics debris ball with player_index = -1. It rolls, falls, and collides with other balls and geometry.
• load_real_bass() is called from spawn_thread (not DllMain) to avoid the Windows loader lock deadlock that affects LoadLibraryA calls during DLL initialization.

🔗 Related Documents

• 8-Ball Spawn Mod
• 8-Ball AI System

📂 View source on GitHub

Collision System Deep Dive

Overview

Hamsterball uses a spatial tree (octree) for broad-phase collision detection,
with AABB (Axis-Aligned Bounding Box) tests and per-triangle collision mesh
processing for narrow-phase. Ball_AdvancePositionOrCollision (0x4564C0) is the
main physics entry point that delegates to collision handlers via vtable dispatch.

Spatial Tree (Octree)

Collision_TraverseSpatialTree (0x465EF0)

Recursive traversal of the octree structure. For each node:

1. Descend children (AthenaList at node+0x18):

   • Get first child from node+0x424
   • For each child: recurse into Collision_TraverseSpatialTree(child, aabb, result_list)
   • Increment iterator at node+0x20

2. Process leaf data (AthenaList at node+0x2C):

   • Get collision mesh buffer from node+0x438
   • For each collision mesh buffer:
     • For each vertex group (3 vertices per face = 1 triangle):
       • AABB_ContainsPoint(param_1, vx, vy, vz)
       • If contained: AthenaList_Append(param_2, vertex_ptr)

AABB_ContainsPoint

Tests whether a point (x, y, z) is inside an axis-aligned bounding box.
Returns 0 (outside) or 1 (inside).

CollisionMesh Structure (0xCB0 bytes)

CollisionMesh_ctor (0x456D80)

CollisionMesh_ctor(this, scene):
  this->vtable = 0x4D8E10  // Mesh_DeletingDtor
  this->scene = scene       // +0x10
  AthenaList_Init(this + 0x18)   // children
  AthenaList_Init(this + 0x430)  // faces
  AthenaList_Init(this + 0x848)  // mesh data
  this->flags = 0          // +0xC74
  this->aabb_min = {0,0,0} // +0xCA4
  this->aabb_max = {0,0,0} // +0xCA8
  this->state = 0          // +0xCAC
  Ball_InitBattleMode(this)

Collision Event Dispatch (Per-Board Handlers → Shared Base)

IMPORTANT: There is no single "Level" or "Arena" handler. Almost every board type overrides vtable[0x1D] (+0x74) with its own unique collision handler. Each processes board-specific events, then falls through to DispatchCollisionEvents (0x40C5D0) as the shared base. Arena (Rumble) boards have their own separate vtables with separate handlers.

Race Board Handlers

Arena (Rumble) Board Handlers

Board vtable[0x1D] (board-specific handler)
  ├─ Process board-specific events (if event name matches)
  │   └─ Return early (for some events) OR fall through
  └─ DispatchCollisionEvents (0x40C5D0) — shared base handler
      └─ Process universal events (N:GOAL, N:TARPIT, N:WATER, E:JUMP, etc.)

Tower Events (TowerCollisionEvents)

Expert Events (ExpertCollisionEvents)

Base Events (DispatchCollisionEvents)

Event strings can include <TIME> XML tags for timed events.

Ball Physics Pipeline

Ball_AdvancePositionOrCollision (0x4564C0)

6-phase physics pipeline:

1. Free Lists: Release trail point and collision marker lists
2. Input Velocity: Add input force to velocity, clamp to max_speed
3. Damping: Apply damping formula: (1-dt) + (1-damping)*dt
4. Collision: If collision flag set → vtable[0x1C] dispatch
5. Gravity: Apply gravity with 0.95 damping constant
6. Trail Recording: Record trail points on non-collision frames

Ball Collision Constants

Ball Struct Physics Offsets

Face/Vertex Data Format

CollisionFace Structure (0x18 bytes)

MeshBuffer Structure (0x14 bytes)

.COL Binary Format

Header: "COL\0" (4 bytes)
uint32 vertex_count
uint32 face_count
uint16 vertex_coords[vertex_count * 3]  // 16-bit fixed-point
float positions[vertex_count * 3]        // 32-bit float positions

Key Collision Functions

Rotator System (Gears, Swirls, Spinny Objects)

Spinning objects in Hamsterball physically carry the ball using a two-function system:

1. Rotator_AddBall (0x43B6F0) — called on collision with N:ONROTATOR, N:SPINNY, or N:SWIRL
2. Catapult_Update (0x43E600) — called every frame, applies rotation matrix to tracked balls

How it works

When the ball touches a spinning object's collision surface, the collision handler calls Rotator_AddBall(scene, ball). This function:

1. Searches the rotator's AthenaList (at scene+0x10F0) for the ball pointer
2. If found: resets the entry's tick counter to 10 (ball already tracked — keeps it on the rotator)
3. If not found: allocates an 8-byte struct [ball_ptr, tick_counter=10] and appends it to the list

Every frame, Catapult_Update iterates the ball-tracking list:

• Decrements each entry's tick counter
• If counter reaches 0: frees the entry (ball released from rotator)
• Otherwise: applies the object's rotation matrix to the ball's position (ball+0x164/+0x168/+0x16C) and velocity (ball+0xCA4/+0xCA8/+0xCAC)

10-frame grace period (not a carry limit)

The counter resets to 10 every frame the ball remains in contact with the rotator surface, because Ball_FallUpdate fires the collision event every frame. The countdown only starts ticking down after the ball leaves the rotator. This means:

• While on the rotator: ball stays tracked indefinitely (counter keeps resetting to 10)
• After leaving: 10 more frames of rotation before release (smooth transition)

Rotator/Catapult struct offsets

Event → collision handler mapping

🔗 Related Documents

• Custom N
• Event Plane System

📂 View source on GitHub

00 - RE Mindset

Reverse engineering is evidence-based reconstruction.

Core Principles

1. The binary is the ground truth. Tools and docs are hypotheses.
2. Never trust a name without evidence. Even a pretty function name is just a label.
3. Work from the known to the unknown. Start with strings, imports, and entry points; move toward internal logic.
4. Cross-reference everything. A struct offset needs at least two decompilations before it is trustworthy.
5. Write as you go. A session without notes is a session you will repeat.

When You Are Stuck

• Look for the constructor. It tells you field sizes and default values.
• Look for the destructor. It tells you nested objects and cleanup order.
• Look for the update loop. It tells you which fields actually matter.
• Look for string comparisons. They reveal state machines and object types.
• Look for magic numbers. 0x3F800000 is 1.0f; 0x40400000 is 3.0f.

Reproducibility

Record:

• Binary MD5/SHA256
• Tool versions (Ghidra, plugin, OS)
• Exact commands run
• Failed hypotheses, not just successes

🔗 Related Documents

• Drawbridge & Trapdoor
• Audio System

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/01-BOOTSTRAP.md)

01 - Bootstrap a Hamsterball RE Project

This guide assumes you have access to the hamsterball-re repo and the original game assets.

1. Workspace Layout

hamsterball-re/
├── originals/              # NEVER modify these
│   ├── installer/
│   └── installed/
│       └── extracted/
│           └── Hamsterball.exe
├── analysis/
│   ├── ghidra/
│   │   ├── HamsterballProject/
│   │   ├── scripts/
│   │   ├── structs/
│   │   └── renames_backup.json
│   ├── code_ref/
│   └── screenshots/
├── docs/                   # Human-readable findings
├── reimpl/                 # Reimplementation source
└── tools/                  # Custom RE tooling

2. Hash Everything First

Before analysis, record integrity baselines:

cd ~/hamsterball-re
python3 - <<'PY'
import hashlib, json, os
root = "originals/installed/extracted"
hashes = {}
for dirpath, _, files in os.walk(root):
    for f in files:
        p = os.path.join(dirpath, f)
        with open(p, "rb") as fh:
            data = fh.read()
            hashes[os.path.relpath(p, root)] = {
                "md5": hashlib.md5(data).hexdigest(),
                "sha256": hashlib.sha256(data).hexdigest(),
                "size": len(data)
            }
with open("docs/FILE_HASHES.json", "w") as out:
    json.dump(hashes, out, indent=2)
print("hashed", len(hashes), "files")
PY

Known good MD5 for Hamsterball.exe: 7d25019366b8d7f55906325bd630d7fe.

3. Initial Binary Reconnaissance

# File type and PE layout
file Hamsterball.exe
objdump -x Hamsterball.exe | head -80

# String sweeps
strings Hamsterball.exe | grep -iE '\.(dll|mesh|world|xml|wav|png|bmp|mo3)'
strings Hamsterball.exe | grep -iE 'direct3d|d3d|dinput|dsound|bass'
strings Hamsterball.exe | grep -iE 'menu|level|race|score|hamster'

Key findings to expect:

• PE32 i386, Visual C++ 2003 era
• Imports from D3D8.dll, DINPUT8.dll, DSOUND.dll, BASS.dll
• Window class name AthenaWindow at ~0x4D9374
• Engine assets under levels\, data\, fonts\

4. PE Analysis With Python

python3 - <<'PY'
import pefile
pe = pefile.PE("originals/installed/extracted/Hamsterball.exe")
print(f"Image base: 0x{pe.OPTIONAL_HEADER.ImageBase:08X}")
print(f"Entry point RVA: 0x{pe.OPTIONAL_HEADER.AddressOfEntryPoint:08X}")
print("Imports:")
for entry in pe.DIRECTORY_ENTRY_IMPORT:
    print(f"  {entry.dll.decode()}: {len(entry.imports)} imports")
PY

5. Asset Discovery

Common asset directories and files:

levels\          # .MESH and .MESHWORLD level files
data\            # HS.CFG save, RaceData.xml, Jukebox.xml, etc.
fonts\           # .description + .png font data
meshes\          # ball, hamster, hazards
sounds\          # .wav SFX
music\           # .mo3 tracker music (BASS)

6. First Wine Run (Optional)

Never background Wine. Instead:

cd originals/installed/extracted
WINEDEBUG=+loaddll timeout 30 wine Hamsterball.exe 2>&1 | tee /tmp/wine_first_run.log

Look for missing DLLs in the log.

🔗 Related Documents

• 02 - Ghidra Setup and GhidraMC

📂 View source on GitHub

01 - Targets and Tools

Supported Binary Formats

Analysis Types

Static analysis: No code execution. Safe and repeatable.

• File headers, strings, imports/exports, disassembly, decompilation.

Dynamic analysis: Code runs under observation.

• Debugging, hooking, memory dumps, API tracing.

Tool List

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

02 - Binary Reconnaissance

Initial Commands (any binary)

file target.exe
strings target.exe | head -50
strings target.exe | grep -iE '\.(dll|so|dylib)'
strings target.exe | grep -E '^[A-Za-z_][A-Za-z0-9_]*$' | sort | uniq -c | sort -rn | head
python3 - <<'PY'
import pefile, hashlib
with open('target.exe','rb') as f: data = f.read()
print('md5', hashlib.md5(data).hexdigest())
print('sha256', hashlib.sha256(data).hexdigest())
pe = pefile.PE('target.exe')
print('imagebase', hex(pe.OPTIONAL_HEADER.ImageBase))
print('entrypoint', hex(pe.OPTIONAL_HEADER.AddressOfEntryPoint))
print('imports')
for entry in pe.DIRECTORY_ENTRY_IMPORT:
    print(' ', entry.dll.decode(), len(entry.imports))
PY

What to Look For

• Import table: reveals graphics/audio/input/network libraries.
• String table: filenames, URLs, error messages, debug paths, class names.
• Sections: large .text, .rdata, .data; unusual names may indicate packing.
• Entropy: packed/encrypted sections have entropy near 8.
• Exports: DLL interfaces, COM classes, plugin APIs.

Red Flags

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/02-GHIDRA-SETUP.md)

02 - Ghidra Setup and GhidraMCP Headless Server

1. Import the Binary

Use Ghidra's headless analyzer (do this once):

export GHIDRA_HOME=/opt/ghidra_12.0.4_PUBLIC
mkdir -p ~/hamsterball-re/analysis/ghidra/HamsterballProject
$GHIDRA_HOME/support/analyzeHeadless \
    ~/hamsterball-re/analysis/ghidra/HamsterballProject \
    Hamsterball \
    -import ~/hamsterball-re/originals/installed/extracted/Hamsterball.exe \
    -overwrite

Warning: -overwrite wipes any existing renames. Only do this if restoring from FUNCTION_MAP.md afterwards.

2. Install / Update GhidraMCP Extension

The project uses GhidraMCP for REST-based decompilation. Extension path:

~/.config/ghidra/ghidra_12.0.4_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP-5.12.0.jar

Update procedure:

cd /tmp && mkdir -p ghidra-mcp-update && cd ghidra-mcp-update
curl -sLO https://github.com/benethington/ghidra-mcp/releases/latest/download/GhidraMCP.zip
curl -sLO https://github.com/benethington/ghidra-mcp/releases/latest/download/bridge_mcp_ghidra.py
unzip -q GhidraMCP.zip -d ~/.config/ghidra/ghidra_12.0.4_PUBLIC/Extensions/GhidraMCP
sudo mkdir -p /opt/ghidra-mcp
sudo cp bridge_mcp_ghidra.py /opt/ghidra-mcp/

3. Start the Headless Server

Use a Hermes background terminal process (do NOT use nohup ... & in foreground):

export GHIDRA_HOME=/opt/ghidra_12.0.4_PUBLIC
MCP_JAR=/home/evan/.config/ghidra/ghidra_12.0.4_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP-5.12.0.jar
CLASSPATH="$MCP_JAR"
for jar in $GHIDRA_HOME/Ghidra/Framework/*/lib/*.jar; do CLASSPATH="${CLASSPATH}:${jar}"; done
for jar in $GHIDRA_HOME/Ghidra/Features/*/lib/*.jar; do CLASSPATH="${CLASSPATH}:${jar}"; done
for jar in $GHIDRA_HOME/Ghidra/Processors/*/lib/*.jar; do CLASSPATH="${CLASSPATH}:${jar}"; done

java -Xmx4g -XX:+UseG1GC \
    -Dghidra.home=$GHIDRA_HOME -Dapplication.name=GhidraMCP \
    -classpath "$CLASSPATH" \
    com.xebyte.headless.GhidraMCPHeadlessServer \
    --port 8089 --bind 127.0.0.1 \
    --project /home/evan/hamsterball-re/analysis/ghidra/HamsterballProject/Hamsterball.gpr \
    --program /Hamsterball.exe \
    > /tmp/ghidra-mcp.log 2>&1

Required flags:

• --project must end in .gpr
• --program must have leading slash (/Hamsterball.exe)

4. Verify the Server

# Health check
curl -s http://127.0.0.1:8089/health

# Expected output:
# {"status":"healthy","version":"5.12.0-headless","program_loaded":true,"program_name":"Hamsterball.exe"}

# Rename coverage
curl -s http://127.0.0.1:8089/compare_programs_documentation

# List functions
curl -s "http://127.0.0.1:8089/list_functions?page=1&limit=5000" | head

# Decompile a known function
curl -s "http://127.0.0.1:8089/decompile_function?address=0x004278E0"

5. Hermes MCP Bridge (Optional)

If Hermes does not auto-discover mcp_ghidra_mcp_* tools, enable the bridge in ~/.hermes/config.yaml:

mcp_servers:
  ghidra-mcp:
    command: python3
    args:
      - /opt/ghidra-mcp/bridge_mcp_ghidra.py
    env:
      GHIDRA_SERVER_URL: http://127.0.0.1:8089/
    timeout: 180
    connect_timeout: 30

Then verify with hermes tools list | grep ghidra.

6. Important Server Quirks

• Use GET with query params, not POST with JSON. Direct POST to /decompile_function returns errors.
• /list_functions returns plain text, not JSON.
• Name lookups (?name=Foo) are unreliable; prefer ?address=0x....
• run_script_inline is broken in headless mode due to OSGi BundleHost issues.

7. Stop / Restart

kill $(pgrep -f GhidraMCPHeadlessServer)
# Wait 2 seconds, then re-run the start command.

🔗 Related Documents

• Reverse Engineering Experiment
• Key Function Decompilations

📂 View source on GitHub

03 - Ghidra Setup

Import Any Binary

/opt/ghidra/support/analyzeHeadless /path/to/project ProjectName -import /path/to/binary -overwrite

Auto-Analysis

Run all default analyzers first. For MSVC binaries, enable:

• Windows PE x86 Propagate External Parameters
• Apply Function Signature Data
• Create Address Tables

Project Hygiene

• Name the project after the binary version.
• Keep an untampered copy of the original.
• Export renames to git regularly.
• Use commit messages like analysis: rename rendering functions @ 0x45xxxx.

Headless Decompilation

Useful for batch work:

/opt/ghidra/support/analyzeHeadless /path/to/project ProjectName -scriptPath ./scripts -postScript DecompileByAddress.java 0x1234 /tmp/out.c

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/03-RENAME-RESTORE.md)

03 - Restore Function Renames from FUNCTION_MAP.md

The Hamsterball project has 975+ hand-labeled functions. The authoritative list lives in docs/FUNCTION_MAP.md. This file explains how to apply those names to a fresh Ghidra project.

1. Prerequisite

• GhidraMCP headless server running on port 8089
• Program loaded (program_loaded: true on /health)

2. Run the Restore Script

cd ~/hamsterball-re
python3 analysis/ghidra/apply_renames.py

The script:

1. Parses docs/FUNCTION_MAP.md for | 0x... | Name | rows.
2. Skips auto-generated names (Catch, Unwind, operator_, thunk_, entry, Start).
3. Sends batches of 50 names to http://127.0.0.1:8089/batch_create_labels.
4. Prints progress and final documentation percentage.

3. Verify Coverage

curl -s http://127.0.0.1:8089/compare_programs_documentation | python3 -m json.tool

Expected final coverage: ~100% (3,781/3,781 functions documented).

4. Export Renames Back to JSON (After Heavy RE Session)

If you add new labels, back them up:

cd ~/hamsterball-re
python3 - <<'PY'
import json, re
renames = []
with open('docs/FUNCTION_MAP.md', 'r') as f:
    for line in f:
        m = re.match(r'\|\s*(0x[0-9a-fA-F]+)\s*\|\s*(\S+.*?)\s*\|', line.strip())
        if m:
            addr, name = m.group(1), m.group(2).strip()
            if name not in ('Address', 'Name', '---'):
                renames.append({'address': addr, 'name': name})
with open('analysis/ghidra/renames_backup.json', 'w') as f:
    json.dump({'renames': renames, 'count': len(renames),
               'timestamp': '2026-06-17', 'source': 'FUNCTION_MAP.md'}, f, indent=2)
print(f"Backed up {len(renames)} renames")
PY

5. Maintaining FUNCTION_MAP.md

When you discover and rename a new function:

1. Add it to docs/FUNCTION_MAP.md in the appropriate subsystem section.
2. Run apply_renames.py to sync Ghidra.
3. Commit both docs/FUNCTION_MAP.md and analysis/ghidra/renames_backup.json.

6. Format Rules for FUNCTION_MAP.md

## Subsystem Name

| Address | Name | Description |
|---------|------|-------------|
| 0x004XXXXX | FunctionName | What it does |

• Address 0x prefix, 8 hex digits.
• Name is one word (no spaces), snake_case allowed.
• Description is concise but specific.

🔗 Related Documents

• 01 - Bootstrap a Hamsterball R

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/04-DECOMP-WORKFLOW.md)

04 - Decompilation and Code-Reference Workflow

1. Single Address Decompile via REST

ADDR=0x0046BD80  # App_Run
curl -s "http://127.0.0.1:8089/decompile_function?address=$ADDR"     > analysis/code_ref/decomp_app_run.c

2. Batch Decompile via Headless Script

When the REST server is slow or unreliable, use a native Ghidra Java script. A template is provided at:

analysis/ghidra/scripts/DecompileByAddress.java

Run it from the repo root:

/opt/ghidra/support/analyzeHeadless \
  $(pwd)/analysis/ghidra/HamsterballProject Hamsterball \
  -scriptPath $(pwd)/analysis/ghidra/scripts \
  -postScript DecompileByAddress.java 0x46EC30 /tmp/decomp_46EC30.c

For multiple addresses, use DecompileMultiAddresses.java (same directory) with a comma-separated address list.

3. Cleaning Decompiled Code

When converting raw Ghidra C to readable reference code:

DO:

• Give variables meaningful names.
• Replace magic numbers with named constants.
• Add section comments (// === physics integration ===).
• Preserve original pointer arithmetic semantics (use PTR_OFF, READ_U8, WRITE_U8 macros).

DO NOT:

• Replace flat __strnicmp chains with switch/enum class.
• Change __thiscall free functions into C++ class methods with early returns.
• Factor repeated pointer arithmetic into accessor methods unless the original did so.

See analysis/code_ref/DispatchCollisionEvents_clean.cpp for an example of a faithful cleanup.

4. Required Reading for New Findings

After decompiling a new function, update these canonical docs:

5. Naming Conventions

6. Cross-Reference Search Patterns

# Find all references to a byte offset in raw decompilations
grep -rn '(int)this + 0xCA8)' analysis/ghidra/decompilations/
grep -rn 'param_1\[0x32a\]' analysis/ghidra/decompilations/   # 0x32a * 4 = 0xCA8

# Find xrefs to a vtable
grep -rn '0x4CF3A0' analysis/code_ref/ docs/ analysis/ghidra/structs/

🔗 Related Documents

• Struct Definitions
• 06 - Common Reverse-Engineerin

📂 View source on GitHub

04 - Naming Strategy

Naming Unknown Functions

Be Conservative

If you only know a function calls Direct3DCreate8, name it D3D8_CreateDevice_Wrapper, not Graphics_Initialize unless you prove it initializes the whole subsystem.

Anti-Pattern: Naming by Call Site

A function called from Ball-related code that actually dereferences CollisionMesh fields should be named CollisionMesh_*, not Ball_*. Check which struct offsets this accesses.

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

05 - Decompilation Without Distortion

The Goal

Produce readable reference code that preserves the original control flow and memory layout.

Cleaning Rules

• Rename variables.
• Name constants and struct offsets.
• Add section comments.
• Keep the original if-chain order.
• Keep the original calling convention.

Forbidden Cleanups

• Replacing flat string-compare chains with switch.
• Changing __thiscall free functions into C++ methods with early returns.
• Factoring repeated pointer arithmetic into accessors unless the original did so.
• Inventing types for unverified offsets.

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/05-STRUCT-VERIFICATION.md)

05 - Struct Offset Verification Methodology

Every documented offset in this project is guilty until proven innocent by raw decompiled C. Human-written comments can be wrong.

1. Confidence Markers

2. Automated Verification Script

A reusable Python verifier is provided at:

python3 docs/agent-knowledge/scripts/verify_struct_offsets.py Scene > /tmp/scene_verify.md

It decompiles the configured list of functions, extracts all (int)this + 0xNNNN and param_1[0xNNN] references, and compares them to the claimed offsets in CLAIMED_OFFSETS.

Template lives at templates/verify_struct_offsets_template.py.

3. Manual Spot-Check Commands

# Direct byte offset in App functions
grep -rn '(int)this + 0x184)' analysis/ghidra/decompilations/app/

# Int-indexed access (multiply by 4)
grep -rn 'param_1\[0x5' analysis/ghidra/decompilations/app/decomp_app_run.c

# Cross-object references (e.g., Ball -> Scene)
grep -rn '0x5dc\|0x5DC' analysis/ghidra/decompilations/ball/

4. Common Offset Confusion Patterns

5. Creating / Extending Structs in Ghidra

The GhidraMCP create_struct API expects a JSON array of fields:

fields = [
    {"name": "vtable",       "offset": 0x000, "type": "pointer"},
    {"name": "owner_ball",   "offset": 0x010, "type": "pointer"},
    {"name": "roll_friction","offset": 0xC64, "type": "float"},
]
# send to create_struct endpoint

Important: add_struct_field works for extending existing structs. import_data_types is not implemented. create_struct requires the JSON array format shown above; key/value and comma-separated field formats are broken.

6. Plate Comments for ECX this-Param Retyping

Ghidra cannot retype register-based this parameters via the API (set_parameter_type fails on ECX). Workaround: use plate comments on functions to document intended types, or manually retype in the Ghidra GUI.

🔗 Related Documents

• 01 - Bootstrap a Hamsterball R

📂 View source on GitHub

06 - Calling Conventions

x86 32-bit

x64

RCX, RDX, R8, R9 for first four integer/pointer args; XMM0-3 for floats. Caller cleans.

ARM64

X0-X7 for args. Stack may be used for extras. Link register X30/LR holds return address.

Detection in Assembly

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/06-MODDING-PATTERNS.md)

06 - Common Reverse-Engineering Patterns

1. Dead Code Detection

A setter is dead code if the field it writes is never read by the main update/render loop, or if it is overwritten every frame by a computed value.

Method:

1. Decompile the setter.
2. Find the main update function for that object.
3. Search all decompilations for reads of the same offset.
4. If zero reads → dead value.

Example: Ball_SetSpeed (historical misname) writes CollisionMesh+0xC64 and +0xC98, but Ball_Update never reads them. The function is actually CollisionMesh_SetFriction and the fields are overwritten by physics.

2. Nested Object Verification

If a constructor does operator_new(size) + SubObject_ctor(...) and stores the result at this + N, that field is a pointer to a nested object.

Pointer chain template:

void* ball = ...;
void** collisionMeshPtr = (void**)((DWORD)ball + 0x1A4);
void* collisionMesh = *collisionMeshPtr;
float* trueVelY = (float*)((DWORD)collisionMesh + 0xCA8);

3. Vtable-Based Function Discovery

Constructors always assign the vtable first. Parse vtable slots as DWORDs to find virtual method addresses.

// Ball vtable at 0x4CF3A0
// [0] Ball_dtor      @ 0x4027F0
// [1] Ball_InitPhysicsDefaults @ 0x405100
// [2] probably Update  @ ...

A function reached only through vtable dispatch has no direct CALLs. Hook the function start directly or patch the vtable slot.

4. Object Spawning Level-Gating Pattern

Objects fall into two categories:

Self-loading: Constructor calls MeshWorld_ctor(..., "hardcoded_path").

• Can be added to any level by patching app+0x23C mode gate.
• Examples: Bonk, Bumper/Rebound.

Scene-dependent: Constructor receives a pre-loaded mesh pointer from a BoardLevel*_ctor.

• Requires both the mode gate patch AND the level constructor to load the sub-mesh.
• Examples: Tipper, Gluebie, BlockDawg, Catapult, BreakBridge, PopCylinder.

5. Calling Game Functions from Injected Code

Most game member functions use __thiscall:

• this in ECX
• Remaining args on stack

typedef void* (__thiscall *Ball_ctor_fn)(void* thisPtr, int scene);
auto BallCtor = (Ball_ctor_fn)0x40AFE0;
void* ball = BallCtor(allocatedMem, (int)scene);

Calling via __cdecl (all args on stack) will crash because ECX contains garbage.

6. The CRT Heap Trap

Never call the game's operator_new / malloc / _free from an injected DLL — the VS2003 Small Block Heap critical sections can deadlock or corrupt.

Fix: Read the private CRT heap handle and use HeapAlloc/HeapFree directly:

HANDLE hCrtHeap = *(HANDLE*)0x005369C0;  // image base 0x400000 + RVA 0x1369C0
void* mem = HeapAlloc(hCrtHeap, 0, 0xC98);

For ASLR safety, compute the runtime address: GetModuleHandle(NULL) + RVA.

7. AI as Vtable Override

AI objects reuse the same struct as the player; behavior differences come from config flags and a vtable thunk:

1. Level loader writes AI config fields (e.g., ball[0x31D] = 1 for is_8ball).
2. Ball_Update checks the flag and calls Ball_ApplyForce vtable slot with AI-computed input.
3. Look for string comparisons (__stricmp) against names like BADBALL, CHASE, HOME, SIZE, SPINDISTANCE.

🔗 Related Documents

• A1 - __thiscall Convention for
• RE — Key Findings Summary

📂 View source on GitHub

07 - Recovering Structs and Globals

Struct Recovery Steps

1. Find constructor. Note operator_new(size) — that is the struct size.
2. Watch vtable assignment. First field confirms object type.
3. Watch sub-object allocations. this + N = operator_new(...) + ctor means pointer to nested object.
4. Watch default writes. They reveal field types.
5. Find update/render function to see which fields are read.

Globals

Offset Confidence

• ✅ Raw decompiled C, 2+ functions
• ⚠️ One function only or comment-only
• ❓ Inferred from size/alignment, no direct evidence

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/07-REIMPL-LESSONS.md)

07 - Reimplementation Lessons Learned

The project produced a working D3D8 reimplementation and learned a great deal about what does/does not match the original. This file captures those lessons so future work does not repeat the same mistakes.

1. Rendering is D3D8 Only

• The original uses Direct3DCreate8, IDirect3DDevice8, DrawPrimitiveUP, CreateVertexBuffer.
• Any OpenGL/SDL2 files in the old repo are leftovers, not the active code.
• Cross-compile with MinGW i686-w64-mingw32-gcc -m32.

2. Wine + llvmpipe Workaround

Original EXE runs under Wine with a d3d8to9 proxy plus software llvmpipe:

# Build/copy d3d8to9 d3d8.dll next to Hamsterball.exe
Xvfb :99 -screen 0 800x600x16 &
DISPLAY=:99 LIBGL_ALWAYS_SOFTWARE=1 wine Hamsterball.exe

This is useful for screenshot/testing but has known rendering bugs:

• D3DRS_LIGHTING=TRUE + D3DFVF_NORMAL ignores normals → flat surfaces.
• Textures may not render even with correct API usage.

3. Lighting Target-Match Approach

Instead of relying on D3D8 material/lighting interpolation (which behaves incorrectly under llvmpipe), define lit/shadow target colors directly:

Formula:

float lit_factor = pow(max(dot(normal, light_dir), 0.0f), 0.35f);
Vec3 color = shadow + (lit - shadow) * lit_factor;

4. Camera Sign Bug

Original Scene_SetCamera computes:

orbit_dir = (cos_a, 0.9, sin_a);  // camera-to-target direction
eye = target + normalize(orbit_dir) * orbit_dist;

A naive reimplementation placing the eye with the opposite sign (target - dir * dist) works for some levels (Level3) but breaks others (Level1, Level2). Use an adaptive heuristic or match the original sign per level.

5. Spawn / Collision Placement

• Ball spawn Y must be derived from actual geometry (probe downward from START object), not from the START object's raw Y coordinate.
• Level3 START1-1 is at Y=-85.4; the track surface is nearby, but blindly spawning at START.y + radius places the ball in empty space.

6. Per-Geometry vs Per-Level Colors

WarmUp (Level1) uses per-geometry pink diffuse on platform faces. Arena levels use Section 1 PLATFORM diffuse colors. Do not hardcode one color scheme globally.

7. Controls

Ball_GetInputForce reads exactly 4 directional DIK codes at InputDevice+0x50C..0x518. There is NO brake key and NO player-jump; jumping is triggered by E:JUMP collision objects only.

8. Avoid Backgrounding Wine Processes

Wine will hang the agent for 50+ minutes if backgrounded. Use timeout 10s, or launch and kill in the same command.

9. Cross-Compiling DSound8

When compiling DSound code with MinGW, include <mmeapi.h> (or <mmreg.h>) before <dsound.h> to get LPWAVEFORMATEX/LPCWAVEFORMATEX.

10. WASM BoxedWine Dead End

BoxedWine WASM cannot run D3D8/D3D9 games in the browser. The WASM port requires a native SDL2/WebGL reimplementation, not the original EXE.

🔗 Related Documents

• 01 - Bootstrap a Hamsterball R

📂 View source on GitHub

08 - Object-Oriented Patterns

Vtables

A vtable is an array of function pointers stored in .rdata.

// Constructor assigns vtable first
this->vtable = &KnownVtable;

// Slot N = vtable + N*4 (32-bit) or N*8 (64-bit)

Use vtables to map:

• Destructor slot 0
• Virtual methods 1..N
• Multiple inheritance may have multiple vtables

Constructors / Destructors

// In constructor:
this->vtable = &LiveVtable;   // most-derived
SubObject_ctor(this + N);

// In destructor:
this->vtable = &BaseVtable;    // base
SubObject_dtor(this + N);
operator_delete(this);

Multiple Inheritance

A class with multiple bases has multiple vtable pointers, often at +0, +N.
Watch for destructors that restore a different vtable than the constructor sets.

🔗 Related Documents

• 00 - RE Mindset

📂 [View source on GitHub](https://github.com/evangit2/hamsterball-re/blob/master/docs/agent-knowledge/08-TROUBLESHOOTING.md)

08 - Troubleshooting Known Failure Modes

Ghidra / GhidraMCP

Server returns program_loaded: false

1. Read /tmp/ghidra-mcp.log.
2. Confirm --project ends in .gpr and --program starts with /.
3. Re-import with analyzeHeadless if the program was never loaded.
4. After re-import, restore renames from docs/FUNCTION_MAP.md.

run_script_inline fails with BundleHost error

Inline Python/Ghidra scripts are broken in headless mode. Use native Java scripts in analysis/ghidra/scripts/ instead.

MCP tools missing from Hermes

1. Check ~/.hermes/config.yaml for the mcp_servers: ghidra-mcp: bridge block.
2. Verify /opt/ghidra-mcp/bridge_mcp_ghidra.py exists.
3. Fall back to direct curl GET requests.

Decompile by name returns "Address or function name is required"

Use ?address=0x... instead of ?name=.... Name lookups are unreliable.

Tools / Environment

pip vs python3 mismatch

This machine has python3=3.11.15 with no pip module; pip points to python3.12. Use uv or a venv for Python dependencies.

Web search / web extract hanging

Ensure FIRECRAWL_API_KEY and FIRECRAWL_API_URL are set in the Hermes config pointing to the Guanaco router (or disable web fallback).

Guanaco router AttributeError (UsageConfig missing fields)

The installed guanaco package is older than the repo code. Fix:

cd ~/.guanaco/repo
source ~/.guanaco/venv/bin/activate
pip install -e .

Binary / RE

Spawned BadBall crashes

• Verify __thiscall convention.
• Verify ECX = allocated memory.
• Ensure the Scene pointer and CollisionLevel pointer at Scene+0x440 are valid.
• Use HeapAlloc on the game's CRT heap, not operator_new from a DLL.

Camera geometry invisible

Try both eye = target + dir*dist and eye = target - dir*dist or sample which side has vertices in front of the camera.

Textures not rendering under Wine/llvmpipe

Programmatic textures via CreateTexture + LockRect work; loaded BMP/PNG textures may not. Use runtime-generated checker textures with D3DTOP_MODULATE for correct per-pixel modulation.

Commit Safety

Never commit

• Original binaries (.exe, .dll)
• Installer packages
• User credentials or API tokens
• Save games or registry data

Always commit

• docs/FUNCTION_MAP.md
• analysis/ghidra/renames_backup.json
• analysis/ghidra/structs/*.h
• Clean C++ reference reconstructions in analysis/code_ref/

🔗 Related Documents

• 01 - Bootstrap a Hamsterball R

📂 View source on GitHub

09 - Dynamic Analysis

Debugger Uses

• Set breakpoint on suspected function, observe args.
• Watch memory writes to structs.
• Capture call stack for crashes.
• Trace API calls (CreateFile, LoadLibrary, etc.).

Hooking

Safe Hook Checklist

• Match calling convention exactly.
• Preserve registers not used by your hook.
• Do not call CRT allocators from injected threads if the target uses a private heap.
• Log before changing state.

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

10 - Subsystem Patterns

Graphics

Look for Direct3DCreate8/9, CreateWindowEx, RegisterClass, wglCreateContext, SDL_CreateWindow.

Input

Look for DirectInput8Create, GetAsyncKeyState, RegisterRawInputDevices, XInput.

Audio

Look for DirectSoundCreate, BASS_Init, waveOutOpen, OpenAL.

File Formats

Binary formats often follow:

• Magic / version
• Count fields
• Fixed-size records or length-prefixed strings
• Float arrays (3 or 16 floats for 3D transforms)

Event Systems

Many older games use flat string comparison chains:

if (__stricmp(name, "E:JUMP") == 0) { ... }
if (__stricmp(name, "E:ACTION") == 0) { ... }

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

11 - Verification

Every Claim Needs Evidence

Falsification

Actively look for evidence against your hypothesis:

• Search other functions for the same offset.
• Check if a setter's field is ever read.
• Check if a flag is overwritten every frame.

Peer-Review Checklist

Before committing a finding:

1. Can another agent reproduce the address from the doc?
2. Is the binary hash stated?
3. Are confidence markers applied to every claim?
4. Are wrong guesses removed rather than left commented out?

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

12 - Troubleshooting Common Dead Ends

Decompilation Looks Nonsensical

• Check that the binary base is correct.
• Check that you are analyzing the right code (thumb vs ARM, 16-bit vs 32-bit).
• Look at raw disassembly alongside decompilation.

Function Has No Xrefs

• It may be reached through a vtable.
• It may be an export or callback.
• It may be dead code.

Strings Do Not Match Behavior

• Strings may be old or unused.
• The same string may have multiple encoding blocks.
• Look for the code that references the string, not the string itself.

Tool Hangs

• Don't background long-running native tools.
• Use timeout.
• For servers, use Hermes background=true with health checks.

Dynamic Analysis Crashes

• Verify calling convention.
• Verify stack alignment.
• Check for anti-debug (TLS callbacks, timing checks, debug registers).

🔗 Related Documents

• 00 - RE Mindset

📂 View source on GitHub

Hamsterball 8-Ball AI System

Overview

The "8-ball" or "BADBALL" is an AI-controlled enemy ball that appears in single-player race levels. It is a fully autonomous ball object with a simple chase-and-spin behavior designed to interfere with the player. The AI is stateless — no pathfinding, no planning, just a position-seeking force vector updated every frame.

Key insight: The 8-ball is NOT a separate object type. It is a standard Ball instance with NPC flags set. The AI code lives inside the same Ball_Update function (vtable [0x10] at 0x408390 wrapping 0x405E00) that runs on every ball every frame. For player balls, the AI block is skipped because is_8ball = 0. There is no separate 8-ball update function — all balls share the same vtable and the same tick.

Critical consequence: If you set ball[0x31D] = 1 on a player ball, that player ball will execute the 8-ball AI and chase other balls automatically. The AI is a conditional block inside the universal update, not a separate object system.

BADBALL MESHWORLD Format

In MESHWORLD level data, BADBALL objects are defined with typed parameters:

BADBALL pos_x pos_y pos_z
  CHASE distance
  HOME distance
  SIZE radius
  SPINDISTANCE radius

Parameters

Example from Level Data

BADBALL 120.0 50.0 200.0
  CHASE 800
  HOME 400
  SPINDISTANCE 50

This 8-ball:

• Spawns at (120, 50, 200)
• Only chases when player is within 800 units
• Only chases when itself is within 400 units of spawn
• Adds a 50-unit circular wobble to its target position

AI Activation Conditions

The 8-ball AI runs inside Ball_Update (vtable slot [0x10] at 0x408390) ONLY when either condition is true:

if (ball[0x31d] != 0 || scene[0x237] != 0) {
    // Run 8-ball AI
}

Key: 0x31d is set to 1 during CreateBadBall() and cleared during level transitions. The AI block is skipped entirely for normal player balls.

AI Behavior: Two Modes

Mode 1: Direct Chase (when no BADBALL config)

If no CHASE/HOME parameters were set, the AI simply seeks the nearest valid ball:

// Find nearest valid target ball
float best_dist = 999999.0;
Ball* target = nullptr;
for (each ball in scene->ball_list) {
    if (ball->race_active &&               // [0x768] — ball is in active race
        !ball->is_falling &&               // [0x2f9] — not currently falling/respawning
        ball->player_index != -1 &&        // [0x18] — has a valid player
        !ball->is_teleporting &&           // [0x324] — not in teleport
        scene->some_mode_flag) {           // [0x3a4c]
        
        float dist = Math_FastDistance2D(8ball->pos.x, 8ball->pos.z,
                                          ball->pos.x, ball->pos.z);
        if (dist < best_dist) {
            best_dist = dist;
            target = ball;
        }
    }
}

Target validity check breakdown:

• race_active (0x768): Ball is actively racing (not in menu, not finished)
• !is_falling (0x2f9): Ball is not in a fall/respawn state
• player_index != -1 (0x18): Ball has a player/controller assigned
• !is_teleporting (0x324): Ball is not currently teleporting
• scene[0x3a4c]: Some scene-level mode flag (possibly "race in progress")

Mode 2: BADBALL Configured Chase

When CHASE and HOME are set, additional distance checks gate the behavior:

// Only chase if:
// 1. Random roll succeeds (RNG < threshold)
// 2. Player is within CHASE distance
// 3. 8-ball is within HOME distance from its spawn

float rng = RandomFloat();
if (rng < threshold &&
    dist_to_player < ball[0x31c] &&    // CHASE parameter
    dist_from_home < ball[0x31b]) {   // HOME parameter
    
    target = player_ball;
}

Target Computation: Spin Wobble

The 8-ball's target position is NOT the player's exact position. It adds a circular wobble using SPINDISTANCE:

// Base target = spawn position (HOME position, stored at [0x318/0x319/0x31A])
Vec3 target = {
    ball[0x318],  // spawn X
    ball[0x319],  // spawn Y
    ball[0x31A]   // spawn Z
};

// Add spin wobble
float spin_angle = ball[0x31e] * spin_speed;  // [0x31e] increments each frame
target.x += sin(spin_angle) * ball[799];      // ball[799] = SPINDISTANCE
target.z += cos(spin_angle) * ball[799];

// Increment spin counter
ball[0x31e] += 0.05;  // _DAT_004cf48c ≈ 0.05

Key insight: The spin makes the 8-ball orbit around its HOME point while chasing, creating a "probing" behavior rather than a direct homing missile.

Force Application

Once the target is computed, the AI applies force toward it:

// Compute direction to target
float dx = target.x - ball->pos.x;   // [0x59]
float dy = target.y - ball->pos.z;   // [0x5B] — note: using Z as Y in this code
float dz = target.z - ball->pos.y;   // [0x5A]

// Normalize
float dist_sq = dx*dx + dy*dy + dz*dz;
float dist = sqrt(dist_sq);
if (dist > 1.0) {
    dx /= dist;
    dy /= dist;
    dz /= dist;
}

// If 8-ball is smaller than target ball, REVERSE direction (flee!)
if (8ball->radius < target->radius * 0.9) {
    dx = -dx;
    dy = -dy;
    dz = -dz;
}

// Apply force via vtable call
// vtable[0x14] = Ball_ApplyForceWithMultipliers(this, dirX, dirY, dirZ, multiplier)
ball->vtable[0x14](ball, dx, 0.0, dz);

Flee behavior: If the 8-ball's radius is smaller than the target's radius × 0.9, it runs away instead of chasing. This can happen with power-up balls or when the player has grown.

Ball Struct: AI-Relevant Fields

8-Ball Config (set by CreateBadBall())