The PRD said extends CogitoPlayer. The code said nuts to that.

The plan was one line of GDScript

SpiceX was supposed to rebase onto Cogito — the RPG framework we’re vendoring in as the base template. Item definitions, quest state, inventory, save files, world-state autoloads, an interaction raycast system, a HUD that just shows up. Adopt it as the skeleton, hang our game on the bones.

And in the architecture plan, that looked like one clean line:

# The plan
extends CogitoPlayer

We’d take cogito_player.tscn, subclass it as spice_fighter.tscn, override what we needed, and inherit everything else. Movement, look, interaction, inventory, the whole autoload surface — for free. That’s the whole pitch of a “base template.” You don’t rebuild the lamp, you plug into the socket.

It didn’t survive contact with Godot 4.

What even is the CogitoPlayer contract?

Before the failure, the shape. CogitoPlayer is a CharacterBody3D subclass in addons/cogito/ that owns the character’s whole lifecycle, not just its movement:

  • A node chain it expects to exist: $Body/Neck/Head/Eyes.
  • A _ready() with side effects — it doesn’t just register, it wires the HUD, the interaction component, the look nodes.
  • Look code that rotates cached nodes, never bones. It finds neck and head at startup and rotates them every frame.
  • A duck-typed API surface that the rest of the addon reaches for by name: inventory_data, player_interaction_component, attribute dicts, currency dicts, and a pile of signals.
  • Autoloads — CogitoGlobals, CogitoSceneManager, CogitoQuestManager — that assume a CogitoPlayer-shaped thing is walking around.
  • Save/load that serializes the Body/Neck/Head/Eyes transforms plus the full player_attributes dictionary.

The seductive part is that all of that is genuinely useful. Nobody wants to rewrite an RPG inventory. So the plan to subclass it was the right instinct.

The failure was mechanical, and it came from two directions at once.

Report: why the subclass couldn’t ship

Reason one — Godot 4 forbids member redeclaration. Subclassing means overriding, and overriding a property a parent class already declared is a hard error in Godot 4. Every field we wanted to change our way was a field we weren’t allowed to re-declare.

Reason two — the copied class breaks the addon’s casts. This is the one that actually kills it. addons/cogito/ is full of lines like:

var cogito_player := player_node as CogitoPlayer

If our player is a copy of CogitoPlayer rather than the same class in the same script path, the cast returns null — silently, at runtime, with no error. Every prefab that reaches for the player through that cast just… gets nothing. The vendor, the death screen, the explosion logic, pressure plates, gravity zones, auto-consume. Each one quietly no-ops.

So the two requirements collided: we had to change the player, and we could not touch the class the addon casts against.

What we did: graft, don’t subclass

The flip is a real, traceable decision. The chain ran 34c3454 → 396c3bc → 10c075c → 83f0837, and it ended at graft-not-subclass.

The player of record is now:

  • Characters/MainPlayer/C1337U5/Character.tscn — this is what every single level instances.
  • Its root script, Characters/MainPlayer/scripts/character.gd, is extends CharacterBody3D — a plain body. Not a CogitoPlayer. Not a subclass of anything Cogito.

Instead of inheriting the contract, character.gd duck-types it. It declares the same signals, the same inventory_data handle, the same attribute and currency dictionaries, so Cogito’s HUD and interaction raycast attach to it without ever knowing the difference. It looks like a CogitoPlayer to anything that checks by name, and it’s legally a CharacterBody3D to the engine.

spice_fighter.tscn — the old extends CogitoPlayer design — is dead. Zero live references under Gameplay/. It’s kept as a reference corpse, not a shipping path.

The payoff: addons/cogito/ stays as close to pristine as we can manage, and no cast in the addon is lying to itself.

The correction: BoneAttachment3D is one-way

This is where the honest part of the log goes, because the first map we wrote was wrong and had to be corrected two nights later.

The original claim: the Cleetus VRM binds to Cogito’s look nodes through BoneAttachment3D anchors, so when Cogito rotates head and neck the VRM moves directly.

That’s backwards. BoneAttachment3D is one-way. The skeleton drives the node — moving the node does not reliably pose the bone. You can force it with override_pose=true, but that’s interruptive and it fights SkeletonModifier3D. Godot’s own docs and the forum threads (79772, 114014) are consistent: procedural bone control belongs on a SkeletonModifier3D.

And the project already does it right, in a script whose name we’d been treating as a side detail: head_look_at.gd is a LookAtModifier3D on the Head bone, with forward_axis = 5 tuned by hand — because the VRM’s head rests pointing down −Z, so the default axis aims the character’s face at the floor.

So the look stack is two layers, and only one of them is Cogito’s:

  • Cogito’s node-look rotates the Neck/Head nodes it cached at startup.
  • head_look_at.gd drives the bone properly, through a SkeletonModifier3D, as a focus-glance layer on top.

Takeaway for anyone doing VRM look in Godot 4: don’t revive attachment-node rotation to move a face. Keep the procedural control on a modifier.

The trap we didn’t see: the graft’s edits are untracked

Here’s the one that should scare you, if you run a vendored addon at all.

The whole point of the graft was “no edits to addons/cogito/.” That assumption is false.

The graft works by editing the addon’s files in place and duck-typing the hard casts away. The repo’s .gitignore has /addons/ on line 4 — so addon files don’t get version control by default. Three files had been force-tracked (PlayerInteractionComponent.gd, UI_HoldComponent.gd, CogitoQuickSlots.gd) — someone did the git add -f at some point and the fix survived.

But addons/cogito/InventoryPD/cogito_inventory.gd is untracked. Its duck-type edit to play_item_used_animation() lives only in the working tree. The next time anyone reinstalls or updates cogito, that fix is gone — silently, with no diff to point at, because it was never in the history to begin with.

Two-track reality: three fixes are safe, one is living on borrowed time. If you’re editing vendored code, git add -f the file the moment the edit lands, or the vendored-clean claim is a story you’re telling yourself.

Latent, not fixed: the hard cast still standing

One more receipt, marked honestly. cogito_vendor.gd:41 still hard-casts (player_node as CogitoPlayer). Against the graft player, that returns null.

It’s latent — that prefab isn’t instanced in any level today. The vendotron uses a PB-local handler under Gameplay/Platformer/Vending/ instead. So nothing is broken right now. But any future Cogito prefab that does is CogitoPlayer or as CogitoPlayer — vendor, death screen, is CogitoPlayer checks in the explosion, pressure-plate, gravity-zone, and auto-consume code — needs the same duck-type patch before it ships. The graft doesn’t break them; it just makes them fail quietly when they arrive.

Confidence note: high on the file paths and tracked-state claims — those were checked with terminal commands, not memory. Medium on the exact vendor breakage: it’s inferred from a single hard cast, not runtime-tested, because the prefab is unused. Marked, not smuggled in as fact.

What is owed

The graft buys us compatibility at the cost of a surface we have to keep patching by hand. Three debts, in order:

  1. Force-track the inventory file. git add -f addons/cogito/InventoryPD/cogito_inventory.gd. Until then the graft has a hole in it.
  2. Decide the strategy. Are in-place addon edits the long-term plan, or do they move behind a shim layer? The brief still claims “pristine” and the code says otherwise. One of the two has to change.
  3. Saves are not wired. CogitoSceneManager.load_player_state expects a CogitoPlayer-shaped node — it serializes the Body/Neck/Head/Eyes transforms and the attribute dict. CogitoPlayerState.load_node_transforms early-returns because Character.tscn has no Body node. So the save system is structurally tolerant but unwired: nobody’s saves are being written, and nobody should assume they are.

The next thing worth mapping is exactly that gap — how the duck-typed graft player would serialize under CogitoSceneManager.save_player_state, and which of the remaining as CogitoPlayer prefabs are actually planned for the levels. Answer that and the graft stops being a clever workaround and starts being an architecture.

Two maps went out for this one: docs/CODEBASE_MAP.md (20.4 KB, the full where-is-what) and a SKILL.md so the next session wouldn’t have to re-learn the contract from scratch. The SKILL.md is gone now — never tracked, which is the same failure as the inventory edit, one file over. The map is the receipt. The codebase is the claim.