Madagascar Asset Tools

Loads .stream .dff .txd .bsp .txl .rws .lpa

This repo is a collection of tools used for modding the game "Madagascar" (released in 2005).

Contents

• Requirements
• Installation
  • 1. Install uv
  • 2. Clone the repository
  • 3. Install dependencies
  • 4. Running scripts with UV
• Usage
  • CLI
  • Mods

Requirements

• Python >= 3.12
• uv package manager installed

Installation

1. Install uv

If you don't already have uv, install it from the official documentation:

https://docs.astral.sh/uv/getting-started/installation/

Restart your terminal / vscode after installation if necessary.

2. Clone the repository

git clone https://github.com/MaxStache/madagascar-game-asset-tools.git
cd madagascar-game-asset-tools

3. Install dependencies

Run:

uv sync

This automatically creates a virtual environment and installs the dependencies specified by the project.

4. Running scripts with UV

You can run Python scripts through uv without manually activating the virtual environment:

uv run python <script>.py
uv run python -m <module>

Alternatively, activate the virtual environment manually:

# WINDOWS:
.venv\Scripts\activate
# LINUX/MACOS:
.venv/bin/activate

Package layout

Package	Path	Import
madkit (CLI + tools)	src/madkit/	madkit.cli, madkit.tools.*
madformats (file formats)	packages/madformats/	madformats
madlysimple (modding helpers)	packages/madlysimple/	madlysimple
tfbpseudo (AI script compiler + editor)	packages/tfbpseudo/	tfbpseudo
tfbscript (.ai parser/decompiler, tfbtool)	packages/tfbscript/	tfbscript

Each package under packages/ has its own pyproject.toml and can be installed on its own.

Tools are run as modules:

uv run python -m madkit.tools.stream LEVEL.stream
uv run python -m madkit.tools.txd FILE.txd
uv run python -m madkit.tools.analyze FILE
uv run tfbeditor            # TfbPseudo editor

Usage

CLI

uv run madkit unpack LEVEL.stream output/directory/

uv run madkit repack input/directory/ LEVEL.stream

For more information run

uv run madkit --help

or

uv run madkit COMMAND --help

Mods

A mod is a folder in mods/ that edits the stock levels in Levels/:

mods/<name>/
  mod.toml      # name, description
  build.py      # @level(...) functions
  assets/       # files the mod imports (.AI scripts, textures, ...)
  build/        # output (gitignored)

Each @level function receives the named levels, loaded from Levels/<level>.stream. After all functions ran, every level they touched is saved to build/<level>.stream.

from pathlib import Path
from madagascar.mod import level

ASSETS = Path(__file__).parent / "assets"

@level("kingofny")
def gold_coins(kingofny):
    kingofny.assetByName("DG_Coin_Collectable.AI").importFrom(ASSETS / "scripts/DG_Coin_Collectable.AI")

@level("kingofny")          # stacked: runs once per level
@level("kingofny_regen")
def bigger_coins(lvl): ...

@level("street", "kingofny")  # several names: one call with all levels
def alex_to_marty(street, kingofny): ...

uv run madkit config --game-dir "C:/Games/Madagascar"  # once, writes settings.toml
uv run madkit mod init my_mod --level kingofny
uv run madkit mod build my_mod
uv run madkit mod install my_mod

License

Apache-2.0. See LICENSE.

Disclaimer

Unofficial fan project, not affiliated with or endorsed by DreamWorks, Activision or Toys for Bob. No game assets are included, you need your own copy of the game.