# theblacklotus/suicide-barbie architecture

> Architecture diagram of the GitHub repository theblacklotus/suicide-barbie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theblacklotus/suicide-barbie
- Repository: https://github.com/theblacklotus/suicide-barbie

## Overview

1. **What this repo is**
   This is a PSP demoscene production, “Suicide Barbie,” built as a cross-platform runtime that can run on either PlayStation Portable hardware or a PC DirectX 9 build. The architecture is split between a real-time demo player, a set of rendering/animation/content libraries, and an offline asset pipeline that converts authored art into platform-ready binary data.

2. **Top-level separation: runtime vs. content vs. tools**
   The repo has three major zones:
   - `Code/`: all source code, runtime libraries, tests, and third-party deps.
   - `Data/`: authored scene assets, source art, and per-scene build inputs.
   - `Tools/`: conversion utilities, SDKs, and exporter/importer support used to generate the runtime data.
   `ReleaseCandidate/` contains the packaged PSP distribution, including `EBOOT.PBP` and the prebuilt `BarbieData` payload.

3. **Platform architecture**
   The runtime is explicitly dual-targeted:
   - **PSP backend** for the shipped production.
   - **DX9 backend** for desktop playback and authoring iteration.
   Many modules have `dx9/` and `psp/` subdirectories, indicating a shared interface with platform-specific implementations. This is important for the diagram: the engine is not “one renderer,” but a common logic layer with two platform adapters.

4. **Core library layer**
   `Code/Base` provides low-level building blocks:
   - `Common` types/config/macros
   - `Std` portability helpers like endian handling
   - `Math` primitives for linear algebra, quaternions, trig, sqrt
   This layer is dependency-bottom: everything else builds on it, and it keeps the higher modules portable across PSP and PC.

5. **Main content/runtime library: `mutalisk`**
   `Code/Modules/mutalisk` appears to be the central runtime asset/scene library. It contains:
   - mesh and scene abstractions
   - shader/texture support
   - dx9 and psp backends for mesh/texture/platform specifics
   - custom memory management (`dlmalloc`, `malloc.cpp`)
   - headers for runtime types, metadata, and utilities
   In architecture terms, `mutalisk` is the data-model and GPU-facing resource layer that the player and effects systems consume.

6. **Content serialization and import/export: `mutant`**
   `Code/Modules/mutant` is the binary I/O and scene data format layer. It includes:
   - readers/writers
   - compressed binary input/output
   - platform-specific binary I/O
   - animation, hierarchy, clip, sequence, interpolation, evaluator logic
   - type naming/traits/meta support
   This layer bridges authored scene data and the compact runtime `.man/.msk/.msh/.mtx` style files seen under `ReleaseCandidate/` and `Data/`. It is the “serialization boundary” of the system.

7. **Animation subsystem**
   `Code/Modules/animator` and `Code/Modules/player/Animator*` implement animation transforms and blending logic. The runtime uses:
   - transform objects
   - animation algorithms
   - time-driven evaluation
   - per-scene animation playback
   Animation is not isolated; it feeds directly into scene composition and rendering via transformed meshes and effect parameters.

8. **Rendering and shader/effect subsystem**
   `Code/Modules/effects` defines the effect abstraction used by the demo’s visuals. It includes:
   - base effect interfaces
   - a library of named effects like Lambert, Shiny, Unlit, Mirror
   - platform-specific implementations for **DX9** and **PSP**
   - vertex transformation hooks
   The architecture implies effect code is a reusable layer between scene content and platform rendering. Effects are authored once conceptually, then realized per platform backend.

9. **Demo playback / timeline control**
   `Code/Modules/player` is the runtime orchestrator:
   - scene playback
   - demo playback
   - timeline and time control
   - scene player implementations for `dx9` and `psp`
   - transform and animator integration
   The README’s mention of scrubbable time is reflected here: the player is time-centric, driving scenes from a controllable timeline rather than a simple linear “play once” loop.

10. **Lua integration**
   `Code/Modules/lua` provides scripting/property support around `LuaPlayer` and `Properties`. This looks like a control/configuration layer for scene behavior and demo metadata, not the core render loop. In the diagram, it should sit as a higher-level orchestration/input layer feeding scene parameters and event logic.

11. **Scene/content pipeline**
   `Data/DemoTest` contains the authored source scenes, textures, model files, props, and per-scene launch scripts. The content is structured by scene name (`snake`, `beer`, `telephone_s1`, `logo`, etc.), and each scene has platform-specific build outputs under `psp/` in `ReleaseCandidate/`.
   The flow is:
   authored scene assets → export/convert tools → binary runtime assets → scene player/demo runtime.

12. **Offline tools and exporters**
   `Tools/` is a full authoring pipeline:
   - `TransformMesh` / `TransformMesh2` import 3D content from DCC formats via FBX/LightWave-related code.
   - `MutaliskPlayer` and `BasicHLSL2` are desktop-side shader/player tools.
   - `Maya` scripts and plugins support asset export from the DCC side.
   - `bin/` contains compiled helpers like `CompressIntroAnim.exe`, `ImageConverter.exe`, `ImportScene.exe`.
   These tools are the production boundary between artist-authored content and the compact PSP runtime data.

13. **Build and deployment model**
   Root scripts like `bootstrap.sh`, `build.sh`, `emulate.sh`, `psplink.sh` wire up the PSP toolchain and runtime execution paths. The repo also vendors the PSP toolchain bootstrap and includes third-party libraries like `zlib`.
   Deployment targets are:
   - PSP package in `ReleaseCandidate/`
   - emulator/PC playback for validation
   - USB-hosted PSP debugging via psplink

14. **Tests and sample content**
   `Code/Tests` contains multiple focused test apps such as animation, blur, mutalisk, scene, WAV, and PSP stub tests. These are not just unit tests; they are executable integration samples for specific subsystems and platforms.
   `Code/TestData` and `Data/ExportTest2` provide fixtures for validating export/import and scene conversion behavior.

15. **Architectural boundary summary**
   The key boundaries to draw are:
   - **Authoring tools vs. runtime**
   - **Platform-independent content logic vs. PSP/DX9 backends**
   - **Serialization/import-export vs. playback/rendering**
   - **Scene/timeline control vs. low-level mesh/effect execution**
   - **Code vs. packaged release assets**
   This repo is best diagrammed as a production pipeline feeding a dual-platform real-time demo player, with `mutalisk`, `mutant`, `player`, and `effects` forming the core runtime stack.

Main entry points: [`Code/Modules/player`](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/player) (Player), [`Code/Modules/mutant`](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutant) (Mutant), [`Code/Base`](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Base) (Base libs), [`Code/Modules/mutalisk`](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutalisk) (Mutalisk)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_n_base["Base libs<br/>portable foundation"]
  node_n_core["Core<br/>shared headers"]
  node_n_mutalisk["Mutalisk<br/>asset runtime"]
  node_n_mutant["Mutant<br/>serialization I/O"]
  node_n_animator["Animator<br/>blend/eval logic"]
  node_n_effects["Effects<br/>shader library"]
  node_n_player["Player<br/>demo orchestrator"]
  node_n_lua["Lua<br/>scripting layer"]
  node_n_zlib["zlib<br/>compression dep"]
  node_n_tests["Tests<br/>integration samples"]
end

subgraph group_grp_content["Content"]
  node_n_data["Demo assets<br/>authored content"]
  node_n_exporttest["Export fixtures<br/>pipeline fixtures"]
  node_n_release[("Release build<br/>packaged PSP data")]
end

subgraph group_grp_tools["Tools"]
  node_n_transform["TransformMesh<br/>FBX importer"]
  node_n_transform2["TransformMesh2<br/>FBX/LW importer"]
  node_n_mutaliskplayer["MutaliskPlayer<br/>DX9 viewer"]
  node_n_hlsl["BasicHLSL2<br/>shader tool"]
  node_n_maya["Maya support<br/>export scripts"]
  node_n_bins["Tool binaries<br/>compiled converters"]
end

node_n_core -->|"builds on"| node_n_base
node_n_mutalisk -->|"uses"| node_n_base
node_n_mutant -->|"uses"| node_n_base
node_n_animator -->|"uses"| node_n_base
node_n_effects -->|"uses"| node_n_base
node_n_player -->|"uses"| node_n_base
node_n_mutalisk -->|"consumes"| node_n_mutant
node_n_player -->|"drives"| node_n_mutalisk
node_n_player -->|"integrates"| node_n_animator
node_n_player -->|"renders with"| node_n_effects
node_n_lua -->|"configures"| node_n_player
node_n_mutant -->|"compresses with"| node_n_zlib
node_n_mutaliskplayer -->|"exercises"| node_n_mutalisk
node_n_mutaliskplayer -->|"exercises"| node_n_effects
node_n_transform -->|"exports to"| node_n_mutant
node_n_transform2 -->|"exports to"| node_n_mutant
node_n_maya -->|"supports"| node_n_transform
node_n_maya -->|"supports"| node_n_transform2
node_n_bins -->|"produces"| node_n_mutant
node_n_data -->|"feeds"| node_n_transform
node_n_data -->|"feeds"| node_n_transform2
node_n_transform -->|"packages"| node_n_release
node_n_transform2 -->|"packages"| node_n_release
node_n_player -->|"loads"| node_n_release
node_n_tests -->|"validates"| node_n_player
node_n_tests -->|"validates"| node_n_mutalisk
node_n_tests -->|"validates"| node_n_effects
node_n_tests -->|"validates"| node_n_animator
node_n_release -->|"derived from"| node_n_data

click node_n_base "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Base"
click node_n_core "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/core"
click node_n_mutalisk "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutalisk"
click node_n_mutant "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutant"
click node_n_animator "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/animator"
click node_n_effects "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/effects"
click node_n_player "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/player"
click node_n_lua "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/lua"
click node_n_zlib "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/zlib"
click node_n_tests "https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Tests"
click node_n_data "https://github.com/theblacklotus/suicide-barbie/tree/master/Data/DemoTest"
click node_n_exporttest "https://github.com/theblacklotus/suicide-barbie/tree/master/Data/ExportTest2"
click node_n_release "https://github.com/theblacklotus/suicide-barbie/tree/master/ReleaseCandidate"
click node_n_transform "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/TransformMesh"
click node_n_transform2 "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/TransformMesh2"
click node_n_mutaliskplayer "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/MutaliskPlayer"
click node_n_hlsl "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/BasicHLSL2"
click node_n_maya "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/Maya"
click node_n_bins "https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/bin"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_base,node_n_core,node_n_mutalisk,node_n_mutant,node_n_animator,node_n_effects,node_n_player,node_n_lua,node_n_zlib,node_n_tests toneBlue
class node_n_data,node_n_exporttest,node_n_release toneAmber
class node_n_transform,node_n_transform2,node_n_mutaliskplayer,node_n_hlsl,node_n_maya,node_n_bins toneMint
```

## Components

### Runtime

Cross-platform demo player and engine libraries

- [Base libs](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Base): portable foundation · Common types, portability helpers, and math primitives used across the engine. · `Code/Base`
- [Core](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/core): shared headers · Shared module-wide configuration and platform/type glue. · `Code/Modules/core`
- [Mutalisk](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutalisk): asset runtime · Central mesh, scene, shader, and texture runtime layer with PSP and DX9 backends. · `Code/Modules/mutalisk`
- [Mutant](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/mutant): serialization I/O · Binary readers/writers, compressed I/O, and scene/animation data format logic. · `Code/Modules/mutant`
- [Animator](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/animator): blend/eval logic · Animation transforms and algorithms used to evaluate and blend motion. · `Code/Modules/animator`
- [Effects](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/effects): shader library · Reusable visual effect abstractions with DX9 and PSP implementations. · `Code/Modules/effects`
- [Player](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/player): demo orchestrator · Scene playback, timeline control, and runtime coordination for the demo. · `Code/Modules/player`
- [Lua](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Modules/lua): scripting layer · Lua-driven properties and control hooks for scene metadata and behavior. · `Code/Modules/lua`
- [zlib](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/zlib): compression dep · Vendored compression library used by the asset pipeline and runtime I/O. · `Code/zlib`
- [Tests](https://github.com/theblacklotus/suicide-barbie/tree/master/Code/Tests): integration samples · Executable subsystem demos for animation, rendering, scene playback, and platform validation. · `Code/Tests`

### Content

Authored scene assets and packaged release data

- [Demo assets](https://github.com/theblacklotus/suicide-barbie/tree/master/Data/DemoTest): authored content · Scene source files, textures, and authoring inputs for the production. · `Data/DemoTest`
- [Export fixtures](https://github.com/theblacklotus/suicide-barbie/tree/master/Data/ExportTest2): pipeline fixtures · Small binary/content fixtures for validating import/export behavior. · `Data/ExportTest2`
- [Release build](https://github.com/theblacklotus/suicide-barbie/tree/master/ReleaseCandidate): packaged PSP data · Shipped PSP bundle containing EBOOT and prebuilt BarbieData payloads. · `ReleaseCandidate`

### Tools

Offline exporters, converters, and authoring utilities

- [TransformMesh](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/TransformMesh): FBX importer · Desktop import tool for 3D scene conversion and inspection. · `Tools/TransformMesh`
- [TransformMesh2](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/TransformMesh2): FBX/LW importer · Second-generation scene import tool with LightWave and FBX support. · `Tools/TransformMesh2`
- [MutaliskPlayer](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/MutaliskPlayer): DX9 viewer · Desktop scene player and test harness for authoring iteration. · `Tools/MutaliskPlayer`
- [BasicHLSL2](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/BasicHLSL2): shader tool · Desktop shader playground and helper for effect development. · `Tools/BasicHLSL2`
- [Maya support](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/Maya): export scripts · Maya plugins and scripts used to export level and scene data. · `Tools/Maya`
- [Tool binaries](https://github.com/theblacklotus/suicide-barbie/tree/master/Tools/bin): compiled converters · Packaged helper executables for compression, image conversion, and scene import. · `Tools/bin`

## Connections

- Core → Base libs: builds on · Core headers depend on the low-level portable foundation.
- Mutalisk → Base libs: uses · Mutalisk relies on base math and portability support.
- Mutant → Base libs: uses · Mutant uses shared types and portability helpers.
- Animator → Base libs: uses · Animation math and transforms are built on the base layer.
- Effects → Base libs: uses · Effect abstractions and implementations depend on common types and math.
- Player → Base libs: uses · Player timeline and scene control use the base layer.
- Mutalisk → Mutant: consumes · Runtime meshes, scenes, and resources are loaded from Mutant binaries.
- Player → Mutalisk: drives · The player orchestrates scene and resource use through Mutalisk.
- Player → Animator: integrates · Playback coordinates animation transforms and blending.
- Player → Effects: renders with · Scene playback uses effects to realize visuals.
- Lua → Player: configures · Lua properties and scripting feed player-level behavior.
- Mutant → zlib: compresses with · Binary I/O and asset payloads use compression support.
- MutaliskPlayer → Mutalisk: exercises · Desktop viewer targets the Mutalisk runtime layer.
- MutaliskPlayer → Effects: exercises · Viewer uses the same effect layer as the runtime.
- TransformMesh → Mutant: exports to · Import tool generates runtime scene binaries.
- TransformMesh2 → Mutant: exports to · Second importer also feeds the Mutant serialization boundary.
- Maya support → TransformMesh: supports · Maya scripts and plugins support the scene export path.
- Maya support → TransformMesh2: supports · Maya integration supports the updated import/export toolchain.
- Tool binaries → Mutant: produces · Compiled utilities generate compact runtime assets.
- Demo assets → TransformMesh: feeds · Authored scene content is converted by offline import tools.
- Demo assets → TransformMesh2: feeds · Scene source assets also feed the second importer pipeline.
- TransformMesh → Release build: packages · Converted assets are staged into the release payload.
- TransformMesh2 → Release build: packages · Converted assets are staged into the shipped PSP data bundle.
- Player → Release build: loads · The shipped runtime consumes the packaged release data.
- Tests → Player: validates · Executable tests exercise demo playback and subsystems.
- Tests → Mutalisk: validates · Subsystem samples validate the runtime asset layer.
- Tests → Effects: validates · Rendering tests exercise effect implementations and backends.
- Tests → Animator: validates · Animation samples exercise transform and blending logic.
- Release build → Demo assets: derived from · Release content is built from authored scene assets.