How to add a new borg

Administrateur — Wed, 01 Jul 2026 23:58:18 GMT

← Older revision		Revision as of 01:58, 2 July 2026
Line 1:		Line 1:
	Complete, precise description of how a '''new borg variant''' is added to ''Gotcha Force'' (GameCube, JPN <code>GG4J</code>, <code>main.dol</code>), as implemented in the editor's <code>borg/table_externalize.rs</code> (<code>build_add_borg_iso</code>).		Complete, precise description of how a '''new borg variant''' is added to ''Gotcha Force'' (GameCube, JPN <code>GG4J</code>, <code>main.dol</code>), as implemented in the gotcha force editor's <code>borg/table_externalize.rs</code> (<code>build_add_borg_iso</code>).

	All patches are applied to a '''copy''' of the disc image — never the original.		All patches are applied to a '''copy''' of the disc image — never the original.

How to add a new borg

Administrateur — Wed, 01 Jul 2026 23:49:37 GMT

Created page with "Complete, precise description of how a '''new borg variant''' is added to ''Gotcha Force'' (GameCube, JPN <code>GG4J</code>, <code>main.dol</code>), as implemented in the editor's <code>borg/table_externalize.rs</code> (<code>build_add_borg_iso</code>). All patches are applied to a '''copy''' of the disc image — never the original. == 0. The core problem == A borg is identified by <code>borgTypeId = (class << 8) | variant</code>, which is also its asset file name <c..."

New page

Complete, precise description of how a '''new borg variant''' is added to ''Gotcha Force'' (GameCube, JPN <code>GG4J</code>, <code>main.dol</code>), as implemented in the editor's <code>borg/table_externalize.rs</code> (<code>build_add_borg_iso</code>).

All patches are applied to a '''copy''' of the disc image — never the original.

== 0. The core problem ==

A borg is identified by <code>borgTypeId = (class << 8) | variant</code>, which is also its asset file name <code>pl[CC][VV].pzz</code>.

Internally, ''everything'' that describes a borg is split across '''per-class tables hardcoded in the DOL'''. Each table is an array of '''16 base pointers''' (one per class); each base pointer addresses a contiguous sub-table of <code>variantCount[class]</code> fixed-stride records. The per-class variant count is read from a single shared array:

* '''<code>g_BorgVariantCounts</code> @ <code>0x802c2a20</code>''' — <code>byte[16]</code>, one variant count per class (sum = 227), '''shared by every borg table'''.

So to add one variant to a class you must grow '''all''' of these tables '''in lockstep''' and bump the count, otherwise the new variant indexes past the end of every sub-table → crash.

== 1. The 12 parallel tables (BORG_TABLES registry) ==

All are indexed by <code>(class, variant)</code> and all grow together:

{| class="wikitable"
! # !! Table !! base-array VA !! stride !! Contents
|-
| 1 || <code>g_BorgStatTables</code> || <code>0x802dc974</code> || <code>0x0c</code> || GF-energy cost (6 shorts, one per level)
|-
| 2 || <code>g_BorgValue2Table</code> || <code>0x802f23e8</code> || <code>2</code> || type / element index
|-
| 3 || <code>g_BorgLevelStatTable</code> || <code>0x802f2ecc</code> || <code>0x0c</code> || detail-panel level stat
|-
| 4 || <code>g_BorgVariantFlags</code> || <code>0x802dca80</code> || <code>1</code> || per-variant flags
|-
| 5 || <code>g_BorgGroupTable</code> || <code>0x802f21d8</code> || <code>2</code> || encyclopedia group id
|-
| 6 || <code>g_BorgLevelThresholdTables</code> || <code>0x802f2fd8</code> || <code>1</code> || XP-curve index
|-
| 7 || <code>g_BorgParamTables</code> || <code>0x802f1f48</code> || <code>0x168</code> || HP + weapon ammo/recharge (the large one, ~81 KB)
|-
| 8 || <code>g_BorgSetupTables</code> || <code>0x802d27dc</code> || <code>4</code> || pointer to the <code>GF_BorgSetup_CnVm</code> function
|-
| 9 || '''<code>g_ForceAssetTable</code>''' || <code>0x802cfb3c</code> || <code>4</code> || '''the <code>.pzz</code> model AFS fid'''
|-
| 10 || <code>g_BorgName</code> || <code>0x80350698</code> || <code>4</code> || pointer to the name string (Shift-JIS)
|-
| 11 || <code>g_BorgPartEffectTables</code> || <code>0x802d1b1c</code> || <code>4</code> || attachment-part bone re-pin records
|-
| 12 || <code>g_BorgInitAttachSelectorTables</code> || <code>0x802c98fc</code> || <code>1</code> || init-time attach-object selector
|}

Every accessor materializes its base array with the same shape (<code>lis reg, hi</code> + <code>addi/subi base, reg, lo</code>), which is why all 12 can be handled uniformly.

== 2. The key idea: clone an existing variant ==

The new variant is a '''byte-exact clone of an existing variant''' (<code>clone_from</code>). No new data is invented. Because that variant's records '''already live in the DOL''', there is nothing to load — the process simply copies what is already there. The clone therefore inherits valid stats/HP/setup/parts/moveset/name and is a working borg immediately.

== 3. The boot-hook grow (the mechanism) ==

=== 3.1 Why NOT the deferred AFS externalization gate ===

There is an alternative path that copies the tables into a runtime buffer loaded from the AFS. It has a '''fatal flaw for a grown variant''': the new variant reads the table slot, and if the async AFS load has not published yet (mid-scene / async timing) the slot still points at the original DOL base array → the new variant indexes out of bounds → crash. It is '''rejected''' for add-a-borg.

=== 3.2 The boot hook (synchronous, before any read) ===

The grow runs at a verified, post-AFS-mount, single-shot boot point, strictly ''before'' any borg table is read:

* '''<code>GROW_HOOK_VA</code> = <code>0x800881a0</code>''' — originally <code>bl 0x800881d8</code> (<code>GF_AFS_LoadPostInitAudioStreams</code>). It is replaced with a <code>bl</code> to the grow routine.
* The routine '''re-issues''' the displaced <code>bl 0x800881d8</code> itself first, so nothing is skipped.

Three memory regions are used (all are zero-padding "caves", checked empty before writing, so a wrong DOL can never be silently clobbered):

* '''Cave A — config @ <code>0x800034dc</code>''': 12 descriptors of <code>GROW_ENTRY_SIZE = 0x0c</code> bytes each: <code>{ base_va (u32), copy_bytes (u16), stride (u16), clone_off (u16), override_fid (u16) }</code> where <code>copy_bytes = count[class] * stride</code> (the original sub-table length) and <code>clone_off = clone_from * stride</code> (the source record offset).
* '''Cave B — routine @ <code>0x800035b0</code>''': the grow routine (built by <code>assemble_grow_routine</code>).
* The hook @ <code>0x800881a0</code>.

=== 3.3 The routine algorithm (per table) ===

# Re-issue the displaced <code>bl 0x800881d8</code>.
# '''Allocate <code>copy_bytes + stride</code>''' from the '''persistent GF global heap''' via '''<code>GF_QueueGlobalAssetLoad</code> @ <code>0x8002a878</code>''' — ''not'' the HSD pool.
#* ''RE-confirmed reason:'' the HSD pool allocator stores its free-list links '''inside freed payload''', so on a scene transition the buffer's first bytes get clobbered to 0 → a null low-class base → <code>GF_GetBorgStat</code> reads a null pointer → crash. The GF global heap is created once at boot and never reset, so it survives every scene. This early in boot it is nearly empty (~15 MB free) → no OOM.
#* If the alloc returns 0 (OOM), the table is '''skipped''' (its base pointer stays original — never a write-through-null).
# '''Byte-copy''' <code>copy_bytes</code> bytes from <code>base[class0]</code> (the original sub-table) into the new buffer.
# '''Byte-copy''' <code>stride</code> bytes from <code>base[class0] + clone_off</code> (the <code>clone_from</code> record) to <code>new + copy_bytes</code> — this '''appends the new variant'''.
# '''<code>override_fid</code>''' (only <code>g_ForceAssetTable</code>): if non-zero, write it (u32) '''over''' the appended entry, so the new variant's <code>.pzz</code> slot points at its '''own''' copy instead of the cloned source fid.
# '''Publish''': <code>base[class0] = new</code> (swap in the grown sub-table).
# Next table; then <code>blr</code> back to the hook.

Synchronous, no async, no scene-state wait → '''the grown table is live before anything reads it'''.

'''Note on class:''' the routine grows the '''class-0''' slot (<code>base[0]</code>) of each table. The built-and-tested case is therefore '''class 0 → <code>pl000d</code>''', cloned from <code>pl0000</code> (Normal Ninja). The "make it real" steps below are parameterised by <code>class</code>; extending the grow itself to an arbitrary class means pointing each descriptor's <code>base_va</code> at <code>base_array + class*4</code>.

== 4. The independent, editable .pzz ==

The disc is '''100 % full''' (exactly <code>0x57058000</code> = 1.4 GB GameCube capacity; <code>afs_data.afs</code> is the last file, with 0 internal gaps). A borg <code>.pzz</code> is ~1 MB. The space is reclaimed by exploiting the asset map: '''the game loads borgs only via the <code>.pzz</code>''' listed in <code>g_ForceAssetTable</code> (<code>GF_InitForce</code> / <code>FUN_800415c4</code>), so the separate '''<code>pl*_mdl.arc</code> / <code>pl*mot.bin</code> blocks (~60 MB) are unreferenced build artifacts'''.

So (<code>build_add_borg_iso</code>, step 1a):

# Extract the source <code>.pzz</code> (fid from the <code>g_ForceAssetTable</code> catalog).
# <code>pick_unused_borg_asset_drops</code>: pick enough <code>pl*_mdl.arc</code> / <code>pl*mot.bin</code> entries ('''highest fid first''', so the fewest trailing entries relocate) to free the clone's sector-aligned size.
# <code>afs_repack_drop_append</code>: '''repack the AFS contiguously in place''' — dropped entries → TOC <code>0/0</code>, survivors pack down (cumulative AFS resolution requires contiguity), the clone <code>.pzz</code> appended at the new tail, the Filename-Directory pointer @ <code>0x7FFF8</code> nulled — all within the existing extent, '''no disc grow'''.
# The copy's fid becomes the descriptor's '''<code>override_fid</code>''' for <code>g_ForceAssetTable</code> → the new variant gets its '''own, independently-editable topology'''.

Every other table keeps the plain clone (<code>override_fid = 0</code>).

== 5. Making the variant real and selectable (3 DOL patches) ==

# '''<code>g_BorgVariantCounts[class]++</code>''' (@ <code>0x802c2a20 + class</code>) → the game iterates the new variant.
# '''VS validity-mask bit''': <code>VS_MASK_VA 0x802f1f88 + class*8</code> is a per-class 64-bit mask (low word = variants 0..31); set <code>1 << new_variant</code> → the variant can spawn in VS.
# '''Default-roster splice''': the <code>-1</code>-terminated id list (pointer @ '''<code>0x8035a388</code>''', read by <code>GF_BuildDefaultRoster</code>) — read the live list, insert <code>new_id</code> before the <code>0xffff</code> terminator, write the extended list into a free cave word at '''<code>0x802b00ec</code>''' (<code>.text1</code> tail), and repoint the list pointer at it → a '''new game''' grants the new borg.

== 6. The Gecko equivalent (add_borg_gecko, RAM-only) ==

A Gecko code cannot touch the AFS on disc, so there is '''no own <code>.pzz</code>''': the new variant '''shares''' the clone's <code>.pzz</code> (all <code>override_fid = 0</code>). It emits Gecko <code>00</code>/<code>04</code>/<code>06</code> codes for:

* <code>06</code> — the 12-table grow config @ <code>0x800034dc</code>;
* <code>06</code> — the grow routine @ <code>0x800035b0</code> (it re-issues <code>bl 0x800881d8</code> itself);
* <code>04</code> — the boot hook @ <code>0x800881a0</code> → <code>bl</code> to the routine;
* <code>00</code> — the variant-count bump @ <code>0x802c2a20 + class</code>;
* <code>04</code> — the VS-mask bit;
* <code>06</code> — the roster list @ <code>0x802b00ec</code> + <code>04</code> — the roster-pointer repoint @ <code>0x8035a388</code>.

Addresses are masked <code>& 0x01FFFFFF</code> to the MEM1-relative form the base codes expect.

== 7. Verification status ==

* '''Tool-level VERIFIED''': 96 unit tests pass; <code>build_add_borg_iso_on_a_copy</code> produces <code>GF-Loader7.iso</code> where the catalog surfaces the added <code>(0,13)</code> borg with its '''own fid''' (a byte-exact copy of <code>pl0000</code>), <code>counts 13→14</code>, VS-mask bit 13 set, roster pointer repointed, and the grow routine + hook + per-table descriptors landed byte-for-byte.
* '''NOT yet confirmed in-game''': the final proof is to boot <code>GF-Loader7.iso</code> in Dolphin, start a '''new game''', and confirm that <code>pl000d</code> '''and the other borgs''' render (battle + garage) — which would empirically confirm that the dropped <code>pl*_mdl.arc</code> / <code>pl*mot.bin</code> are truly unused.

----

== Summary ==

Add-a-borg = '''12 tables grown in lockstep by a synchronous boot-hook grow''' (clone of an existing variant, allocated from the persistent GF heap) '''+ an own editable <code>.pzz</code> reclaimed by an in-place AFS repack''' (dropping unused <code>pl*_mdl</code>/<code>pl*mot</code> artifacts) '''+ 3 DOL patches''' (variant count, VS mask, default roster). Everything is applied to a copy of the disc.

== Key addresses ==

{| class="wikitable"
! Symbol !! VA !! Role
|-
| <code>g_BorgVariantCounts</code> || <code>0x802c2a20</code> || per-class variant counts (bump target)
|-
| grow config (Cave A) || <code>0x800034dc</code> || 12 × <code>0x0c</code>-byte grow descriptors
|-
| grow routine (Cave B) || <code>0x800035b0</code> || the synchronous grow routine
|-
| boot hook || <code>0x800881a0</code> || <code>bl 0x800881d8</code> retargeted to the routine
|-
| <code>GF_QueueGlobalAssetLoad</code> || <code>0x8002a878</code> || persistent-heap alloc
|-
| <code>g_ForceAssetTable</code> || <code>0x802cfb3c</code> || <code>.pzz</code> fid table (gets <code>override_fid</code>)
|-
| AFS FD pointer || file offset <code>0x7FFF8</code> || nulled after repack
|-
| VS validity mask || <code>0x802f1f88 + class*8</code> || spawn-enable bit
|-
| default-roster pointer || <code>0x8035a388</code> || repointed to the spliced list
|-
| roster list cave || <code>0x802b00ec</code> || the extended <code>-1</code>-terminated id list
|}

[[Category:Gotcha Force]]
[[Category:Reverse Engineering]]

Gotcha Force

Administrateur — Wed, 01 Jul 2026 23:44:58 GMT

Game assets implementation

← Older revision		Revision as of 01:44, 2 July 2026
Line 304:		Line 304:
	* [[Motions]]		* [[Motions]]
	* [[Borg - data file]]		* [[Borg - data file]]
			* [[How to add a new borg]]

	See also [https://github.com/Virtual-World-RE/NeoGF/tree/main/doc our documentation] available on github.		See also [https://github.com/Virtual-World-RE/NeoGF/tree/main/doc our documentation] available on github.

Virtual World R.E. - Recent changes [en]

How to add a new borg

How to add a new borg

Gotcha Force