theblacklotus/suicide-barbie

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.