Madagascar Asset Tools

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

madkit is a collection of tools for modding the game "Madagascar" (released in 2005): a CLI to unpack, repack and build mods for the game's level files, plus viewers for streams and textures.

Contents

• Requirements
• Getting started
  • 1. Install uv
  • 2. Create a modding folder
  • 3. Copy the stock levels
  • 4. Configure madkit
• Mods
• CLI
• Tools
• Development

Requirements

• Python >= 3.12
• uv package manager
• Your own copy of the game

Getting started

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 / VS Code after installation if necessary.

2. Create a modding folder

Make a folder for your mods with its own Python environment, and install madkit into it:

mkdir my-madagascar-mods
cd my-madagascar-mods
uv init --bare
uv add madkit

uv init --bare creates a pyproject.toml, and uv add madkit creates a .venv/ with madkit and everything it needs. Run commands with uv run, or activate the environment once per terminal:

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

To update later: uv add madkit --upgrade.

3. Copy the stock levels

Mods are built from the original .stream level files. Copy the game's Levels/ folder into your modding folder:

my-madagascar-mods/
  Levels/          # copy of <game folder>/Levels, never modified
  pyproject.toml

4. Configure madkit

Tell madkit where the game is installed (once):

uv run madkit config --game-dir "C:/Games/Madagascar"

This writes a settings.toml in the current folder, so run madkit from your modding folder. Use --levels-dir if your stock levels are somewhere other than Levels/.

Mods

Create a mod:

uv run madkit mod init my_mod --level kingofny

This creates:

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

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

from pathlib import Path

from madformats.mod import level
from madformats.stream import RW_StreamFile

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

@level("kingofny")
def gold_coins(kingofny: RW_StreamFile) -> None:
    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): ...

Build it, or build it and copy the levels into the game:

uv run madkit mod build my_mod     # -> mods/my_mod/build/
uv run madkit mod install my_mod   # build + copy into <game folder>/Levels

Back up the game's Levels/ folder before installing mods, so you can restore the originals.

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
uv run madkit COMMAND --help

Tools

GUI tools are run as modules:

uv run python -m madkit.tools.stream LEVEL.stream   # stream viewer
uv run python -m madkit.tools.txd FILE.txd          # texture viewer
uv run python -m madkit.tools.analyze FILE          # RenderWare file viewer
uv run tfbeditor                                    # TfbPseudo AI script editor

Development

To work on madkit itself, clone the repository and install the whole workspace:

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

The repository is a uv workspace with these packages, all installed in editable mode:

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 is published to PyPI on its own.

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.