maddo/Crusader_Decomp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation upgrade

Browse source
This commit is contained in:
MaddoScientisto 2026-04-06 12:19:03 +02:00
commit 56f6099820
23 changed files with 1112 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

115
docs/entity-vm-runtime-owner-resource-layout.md
View file

@ -41,6 +41,24 @@ Current strongest structural claims:
- tail region around `+0x1300..+0x1318` holds runtime budget/default metadata plus the owner-resource helper pointer
- helper attachment lives at `+0x1315/+0x1317`
Live runtime-helper classification added during the 2026-04-05 MCP-upgrade pass:
- `1420:167c Remorse::EntityVmRuntime::AcquireSlotForEntity`
- scans the `0x80`-entry slot table for an existing entity match or the first free slot
- can evict the currently selected slot via the owner-row iterator when the runtime needs to recycle one
- `1420:1866 Remorse::EntityVmRuntime::InitSlotOwnerBuffers`
- reads owner-resource metadata for one slot id
- allocates the two slot-local working buffers later stored at `+0x1e/+0x20` and `+0x22/+0x24`
- seeds the sentinel-filled chunk-state array used by later lazy chunk loads
- `1420:19fd Remorse::EntityVmRuntime::EnsureSlotChunkLoaded`
- lazily materializes one indexed owner chunk for a slot into runtime memory
- marks the chunk present through the slot-local state arrays and updates the runtime-wide budget counters
- `1420:1f24 entity_vm_runtime_apply_to_matching_owner_rows`
- runtime-owned iterator over the owner list, used both for broad cleanup and for filtered slot/category work
- `1420:2040 entity_vm_slot_entry_create_or_clear`
- allocates or clears one `0x26`-byte slot entry record
- gives the current strongest live evidence for the stable slot-entry size and the buffer/cache lane at `+0x1e..+0x24`
Current safe class role:
- long-lived VM root object that owns slot state, owner resource, category-base words, and runtime-wide value budgets
@ -148,6 +166,103 @@ Why this order:
- runtime has clear ownership over the helper and slot table
- context has the richest semantics but also the most unresolved dispatcher behavior
## Live Ghidra Authoring Status
Verified first batch landed in the live `CRUSADER.EXE` session on 2026-04-05.
- Created namespace `Remorse` and class owners `Remorse::EntityVmOwnerResource`, `Remorse::EntityVmRuntime`, and `Remorse::EntityVmContext`.
- Created provisional datatype `/Remorse/EntityVmOwnerResource` with current stable anchors:
- `+0x10 owner_row_table`
- `+0x14 entry_count`
- `+0x18 entry_word_table`
- Created provisional datatype `/Remorse/EntityVmRuntime` with size `0x1319` and only the currently stable tail anchors around the owner-resource attachment lane.
- Created provisional datatype `/Remorse/EntityVmSlotEntry` with size `0x26` and only the currently stable tail buffer fields named:
- `+0x1e owner_buffer_offset`
- `+0x20 owner_buffer_segment`
- `+0x22 chunk_state_offset`
- `+0x24 chunk_state_segment`
- Moved `1430:0000` under `Remorse::EntityVmOwnerResource::Create`.
- Moved `1430:00fd` under `Remorse::EntityVmOwnerResource::Destroy`.
- Moved `1420:1499` under `Remorse::EntityVmRuntime::Create`.
- Moved `1420:1536` under `Remorse::EntityVmRuntime::InitSlots`.
- Moved `1420:1575` under `Remorse::EntityVmRuntime::ReleaseSlots`.
- Moved `1420:1601` under `Remorse::EntityVmRuntime::Destroy`.
- Moved `1420:167c` under `Remorse::EntityVmRuntime::AcquireSlotForEntity` after live decompilation showed a `0x80`-entry scan over the runtime slot table with free-slot fallback and eviction of the currently selected slot.
- Moved `1420:1866` under `Remorse::EntityVmRuntime::InitSlotOwnerBuffers` after live decompilation showed owner-resource reads plus the two slot-local buffer allocations and initial sentinel fill.
- Moved `1420:19fd` under `Remorse::EntityVmRuntime::EnsureSlotChunkLoaded` after live decompilation showed per-slot chunk materialization and cache-presence marking.
- Renamed `1420:1cca` to `entity_vm_runtime_debug_dump_slot_memory` after live decompilation showed a debug-gated walk of the runtime slot list with slot memory usage output.
- Renamed `1420:1f24` to `entity_vm_runtime_apply_to_matching_owner_rows` after live decompilation showed filtered iteration over the runtime owner-row list.
- Renamed `1420:2040` to `entity_vm_slot_entry_create_or_clear` after live decompilation showed allocation and zeroing of one `0x26`-byte slot record.
- Added short decompiler comments at `1430:0000` and `1430:00fd` to preserve the raw `000d:7000` / `000d:70fd` provenance.
- Added short decompiler comments at `1420:1499`, `1420:1536`, `1420:1575`, and `1420:1601` to preserve the runtime-lifecycle provenance and current layout claims.
- Added short decompiler comments at `1420:167c`, `1420:1866`, `1420:19fd`, `1420:1cca`, `1420:1f24`, and `1420:2040` so the slot-table evidence stays visible in the live database.
- Repaired the decompiler health of `1420:1499 Remorse::EntityVmRuntime::Create` after the delete/recreate cycle left it throwing `Low-level Error: Symbol $$undef00000006 extends beyond the end of the address space`; the root cause was the shared allocator helper at `1000:42e2`, whose pointer-return signature decompiled with a hidden `__return_storage_ptr__` and poisoned the caller stack model until it was normalized to an explicit `dword` return plus explicit stack storage.
- Verified second batch landed in the live `CRUSADER.EXE` session on 2026-04-06.
- Moved `1420:0eec` under `Remorse::EntityVmContext::CreateFromSlotIndex`.
- Moved `1420:10b6` under `Remorse::EntityVmContext::FreeBuffer`.
- Moved `1420:10da` under `Remorse::EntityVmContext::SyncGlobalValueAndDispatch`.
- Moved `1420:1162` under `Remorse::EntityVmContext::Destroy`.
- Moved `1420:118f` under `Remorse::EntityVmContext::Save`.
- Moved `1420:1278` under `Remorse::EntityVmContext::Load`.
- Added short decompiler comments at `1420:0eec`, `1420:10b6`, `1420:10da`, `1420:1162`, `1420:118f`, and `1420:1278` to preserve the raw `000d:46ec`, `000d:48b6`, `000d:48da`, `000d:4962`, `000d:498f`, and `000d:4a78` provenance after the class-owner move.
- Verified third batch landed through local PyGhidra on 2026-04-06 after the live `run_write_script(...)` route still returned `404 No context found for request` against the active GUI session.
- Created provisional datatype `/Remorse/EntityVmContext` with size `0x124` and the currently safest stable anchors:
- `+0x32 slot_index`
- `+0x34 value_add_offset`
- `+0xd6/+0xd8 source_stream_offset/source_stream_segment`
- `+0x10c/+0x10e derived_pair_lo/derived_pair_hi`
- `+0x117/+0x119 owner_source_offset/owner_source_segment`
- `+0x123 busy_flag`
- Updated `1420:2040 entity_vm_slot_entry_create_or_clear` to `EntityVmSlotEntry * __cdecl16far entity_vm_slot_entry_create_or_clear(EntityVmSlotEntry * slot_entry)` so the slot-record helper no longer falls back to anonymous `byte *` parameters.
- Updated `1420:167c Remorse::EntityVmRuntime::AcquireSlotForEntity` to return `EntityVmSlotEntry *`, while leaving the third `param_3` entity-like pointer conservative until caller-side role recovery is tighter.
- Updated `1420:1866 Remorse::EntityVmRuntime::InitSlotOwnerBuffers` so the third parameter is now `EntityVmSlotEntry * slot_entry`.
- Updated `1420:1536 Remorse::EntityVmRuntime::InitSlots` to `void __cdecl16far InitSlots(EntityVmRuntime * this)`.
- Updated `1420:1575 Remorse::EntityVmRuntime::ReleaseSlots` to `void __cdecl16far ReleaseSlots(EntityVmRuntime * this)`.
- Tried the same typed-`this` collapse on `1420:1499 Remorse::EntityVmRuntime::Create`, but the pointer-sized `this` variant reintroduced a hidden `__return_storage_ptr__`; the function was restored immediately to the known-good split-word custom-storage signature `dword __cdecl16far Create(word this, word runtime_segment, word owner_type, word owner_id)`.
- Verified fourth live batch landed on 2026-04-06.
- Updated the `local_a` decompiler local in `1420:19fd Remorse::EntityVmRuntime::EnsureSlotChunkLoaded` to `EntityVmSlotEntry *`, so the slot-entry cache path now renders the stable `owner_buffer_offset` and `chunk_state_offset` fields directly instead of anonymous `undefined4` pairs.
- Retried the `EntityVmContext` lifecycle typing pass through live MCP. `apply_class_layout` dry-run for `/Remorse/EntityVmContext` now returns a normal structured preview instead of the earlier null failure, but the real apply path still fails with `Failed to apply this type: Storage size does not match data type size: 2`, and direct live `set_function_this_type` calls on `FreeBuffer`, `SyncGlobalValueAndDispatch`, `Destroy`, `Save`, and `Load` hit the same storage-size mismatch.
- Retried live `run_write_script(...)` with and without explicit target selectors on `CRUSADER.EXE`, but the route still returned `404 No context found for request`, so there is still no live in-session fallback for forcing the dynamic-storage rewrite on the context methods.
- Verified fifth batch landed through local PyGhidra on 2026-04-06 after the live write-side routes still blocked the context pass.
- Updated `1420:0eec Remorse::EntityVmContext::CreateFromSlotIndex` so the first parameter is now `EntityVmContext * this` while preserving the existing `UsecodeProcess *` return type until the constructor/factory semantics are tighter.
- Updated `1420:10b6 FreeBuffer`, `1420:10da SyncGlobalValueAndDispatch`, `1420:1162 Destroy`, `1420:118f Save`, and `1420:1278 Load` so the first parameter is now `EntityVmContext * this` instead of `UsecodeProcess *`.
- That local fallback confirms the newer dynamic-storage rewrite is sufficient for the context lifecycle cluster when applied outside the live GUI session. The remaining MCP issue is deployment/session parity, not whether the typing model itself works.
- Verified sixth analysis-only live batch on 2026-04-06.
- Exercised the new storage-aware prototype route against the two known 16-bit repair cases (`1000:42e2` and `1420:1499`) through the active MCP session. The checked-in source has the new route wiring, but the live GUI plugin still answered with legacy behavior: `/set_function_prototype_storage` returned the old `set_function_prototype` failure body, and `/set_storage_aware_prototype` returned `404 No context found for request`. That confirms the remaining issue is live deployment parity, not endpoint design.
- Rechecked the direct callers of `CreateFromSlotIndex`: `Usecode_ItemCallEvent` plus two `Interpreter_NextUsecodeOp` call sites. The `Usecode_ItemCallEvent` path explicitly calls `CreateFromSlotIndex((EntityVmContext *)0x0,0,...)` as an allocate-and-return factory, and the current caller-side uses immediately consume only base `Process`-style fields such as `procid` and termination flags. The two interpreter call sites likewise just store the returned far pointer in `DX:AX` scratch pairs before later base-process handling.
- That caller evidence is enough to keep the current conservative return type for now: `CreateFromSlotIndex` is clearly manufacturing an `EntityVmContext`, but promoting the return to `EntityVmContext *` before the inheritance/base-process datatype story is explicit would probably make current caller decompilation less clear rather than more clear.
Current live datatype state:
- `/Remorse/EntityVmOwnerResource` is the cleanest landed class in this lane so far.
- `/Remorse/EntityVmRuntime` currently only freezes the stable tail fields and helper pointer, not the full slot-entry schema.
- `/Remorse/EntityVmSlotEntry` now exists as a bounded helper datatype, but only the stable tail buffer-pair fields are named so far.
- `/Remorse/EntityVmContext` now exists and matches the current owned lifecycle cluster, but it still only records the safest field anchors rather than the full embedded mini-VM layout.
- `apply_class_layout` succeeded for `Remorse::EntityVmOwnerResource` but failed for `Remorse::EntityVmRuntime` when the binder tried to apply a `this` type, even though plain ownership moves worked.
- The old `apply_class_layout` dry-run null failure for `Remorse::EntityVmContext` no longer reproduces on the current live server, but the actual write-side `this` typing path is still effectively old-build behavior: the real apply and direct `set_function_this_type` calls still fail on the existing `UsecodeProcess *` lifecycle signatures with `Storage size does not match data type size: 2`.
- The `EntityVmContext` lifecycle signatures are now locally repaired through PyGhidra: `CreateFromSlotIndex` plus `FreeBuffer` / `SyncGlobalValueAndDispatch` / `Destroy` / `Save` / `Load` all carry `EntityVmContext * this` as their first parameter.
- `CreateFromSlotIndex` should still keep its conservative `UsecodeProcess *` return type for the moment. The allocate-and-return behavior is clear, but the known callers currently consume it through base-process fields, and the repo does not yet have an inheritance-aware `EntityVmContext : UsecodeProcess` datatype model that would make a promoted return cleaner across the call sites.
- The runtime lane is now split more accurately: `InitSlots` and `ReleaseSlots` can carry a direct `EntityVmRuntime * this`, while `Create` still needs the split-word custom-storage form to avoid hidden return-storage breakage.
- The first slot-entry prototype batch is tighter now that `EnsureSlotChunkLoaded` carries a real `EntityVmSlotEntry *` local on the acquired-slot path, but the wider slot-entry model is still improved rather than finished.
Current scope of that batch stayed intentionally conservative:
- no final source-format schema naming for the owner rows
- no speculative promotion of additional seg069/070 helper callbacks into owned methods yet
- no speculative promotion of the masked-create wrapper ladder into `EntityVmContext` methods
- no speculative typing yet for the entity-like pointer parameter on `AcquireSlotForEntity`
- no attempt yet to force slot-entry field names beyond the stable `+0x1e..+0x24` tail region and the current conservative helper prototypes
Best immediate next moves after this landed:
- inspect `EnsureSlotChunkLoaded` and adjacent `1420:` helpers again now that `AcquireSlotForEntity` returns `EntityVmSlotEntry *`, and push the slot-entry type one step deeper only where the resulting local/object read is genuinely clearer
- decide whether `CreateFromSlotIndex` can safely promote its return type from `UsecodeProcess *` to `EntityVmContext *`, or whether it should stay a factory-style bridge that only types `this`
- if the context/base-process inheritance story becomes explicit in datatypes, revisit `CreateFromSlotIndex` return typing then; until that point, keep the current `UsecodeProcess *` return even though the body itself clearly builds an `EntityVmContext`
- recover a storage-aware `this`-typing path for `Create` specifically; `InitSlots` and `ReleaseSlots` no longer need to stay in the unresolved set
- redeploy or otherwise verify the live storage-fallback `set_function_this_type` / `apply_class_layout` build, then retry the `EntityVmContext` lifecycle typing pass in-session before dropping back to local PyGhidra
- identify one or two additional strongly owned runtime or owner-resource helpers if the live session exposes them cleanly
- keep the masked-create hub and offset-specialized wrapper ladder outside the class until caller-side role recovery is tighter
## Source-Emission Guidance
If emitted as provisional C++ later, safest early skeleton is: