titan-ultima

TITAN - Tool for Interpreting and Transforming Archival Nodes.

TITAN is a Python CLI and library for working with proprietary data formats from Ultima 8: Pagan, Ultima Underworld II: Labyrinth of Worlds, Ultima 7: The Black Gate / Serpent Isle, Ultima 6: The False Prophet, and the Ultima Online Classic Client. It reads, extracts, converts, inspects, and reconstructs archives, shapes/tiles, palettes, music, speech, maps, world objects, saves, dialogue, and Exult runtime data. Early Ultima 9: Ascension support (FLX archives, TYPENAME.FLX, and sound/*.flx decoding) is also available under titan u9.

Run titan --help, titan uw2 --help, titan u8 --help, titan u7 --help, titan u6 --help, titan u9 --help, titan uo --help, or see the full CLI reference.

Installation

pip install titan-ultima

Requirements:

• Python 3.9+
• NumPy >= 1.24
• Pillow >= 10.0
• Typer >= 0.15
• questionary >= 2.0
• tomli >= 2.0 on Python < 3.11, for titan.toml support

Optional:

• pyvista plus VTK (pip install pyvista) — used by titan uw2 model-render, uw2 map-3d-render, and U9 preview rendering.
• trimesh (pip install trimesh) — used by titan uw2 map-3d-export to write GLB. UU2 standalone model-export needs neither optional package.

Quick Start

Run setup once. It detects common Ultima 8, Ultima 7, and UO install locations, detects Exult runtime folders and the Exult install directory (for exult_bg.flx / exult_si.flx), writes titan.toml, and can extract the U8 shape/glob data used by map rendering.

titan setup

After setup, many commands can use configured paths:

# U8 map render
titan u8 map-render -m 5

# U8 dialogue web viewer
titan dialogue prepare
# Optional: export NPC JSON files and META sidecars
titan dialogue copy
titan dialogue validate
titan dialogue launch

# U7 configured commands
titan u7 map-render --game bg --sc 85 -o britain_bg.png
titan u7 typeflag-dump --game si -f csv -o tfa_si.csv
titan u7 gamedat-info --game si -f detail -o gamedat_info.txt

# UO configured commands, if [uo.game] base is set
titan uo gump-export -o uo_gumps/
titan uo animation-body-names-export -o uo_metadata/

titan setup doesn't detect Ultima 6 installs yet — add [u6.game] base = "<Ultima 6 install>" to titan.toml yourself, or pass -g/--gamedir explicitly on every U6 command:

titan u6 map-render -g "C:/Ultima6" --full -o u6_world.png

Ultima Underworld II install detection is not in titan setup yet. Add its root manually; commands also accept -g/--gamedir:

[uw2.game]
base = "C:/Games/Ultima Underworld 2"

titan uw2 map-render --slots 0 -o castle_maps/
titan uw2 model-render --item 0x158 --item 0x15c -o model_renders/
titan uw2 model-export -o model_exports/
titan uw2 object-info 457
titan uw2 shape-export OBJECTS.GR 302 -o fountain/
titan uw2 shape-export ANIMO.GR 6 -o fountain/

If setup cannot find UO automatically, add it manually:

[uo.game]
base = "C:/Program Files (x86)/Electronic Arts/Ultima Online Classic"

The detailed dialogue web documentation lives in src/titan/dialogue/websrc/READMEd.md.

Capabilities

The table below is the compact command map. The CLI reference is the canonical place for command options, longer examples, and format notes.

Ultima Underworld II

Native UU2 support covers LEV.ARK map extraction, 2D cutaway maps, textured 3D map rendering/GLB export, standalone built-in model rendering/export, PALS.DAT, terrain and .GR image archives, ALLPALS.DAT auxiliary palettes, COMOBJ.DAT render metadata, and OBJECTS.DAT animation descriptors. Map rendering uses verified OBJECTS.GR icons for model-based furniture by default and can optionally project built-in UW2.EXE geometry. Standalone model commands decode that geometry directly, apply palette materials and item-selected TMOBJ.GR textures, then render PNG views or write one OBJ/MTL/PNG asset set per item. Placed meshes use native scale 1, clockwise 45-degree headings, and the 0x0078 model pivot; standalone OBJ vertices are also relative to that pivot. NPC animation archives remain future work.

See UU2 commands.

Ultima 6

U6 support covers reading (and limited save-editing of) the full game: tiles, world/dungeon maps, world objects and eggs, actors, party/game state, story flags, dialogue, and text/reference data.

See the U6 commands reference for the full command list.

Ultima 9 (early)

U9 support is newer and narrower in scope than U8/U7 so far — FLX archives, TYPENAME.FLX, sound/*.flx (Speech.flx, sfx.flx, music.flx) decoding (EA-XA ADPCM, mono and stereo, and EA MicroTalk speech), and 3D model + texture export from static/sappear.flx.

See the U9 commands reference for the full command list.

Ultima Online Classic Client

UO support is export-oriented: it reads the installed Classic Client data directly and writes reviewable PNG, WAV, and CSV outputs. The client directory can be passed per command or configured once as [uo.game] base.

See the UO commands reference for the concise command list.

Common Workflows

U8 Dialogue Web

titan dialogue prepare
# Optional NPC export step
titan dialogue copy
titan dialogue validate
titan dialogue launch

For setup, local development, export behavior, and known dialogue-machine limits, see the dedicated dialogue web README.

U7 Exult Runtime Inspection

# Inspect configured Serpent Isle GAMEDAT, including mod fallback sources.
titan u7 gamedat-info --game si -f detail

# Inspect a mod's packaged patch/initgame.dat archive directly.
titan u7 gamedat-info mods/<mod-name>/patch/initgame.dat --static STATIC/

# Inspect a specific Exult save archive.
titan u7 save-info exult00si.sav
titan u7 save-npcs exult00si.sav --static STATIC/ -f detail
titan u7 save-schedules exult00si.sav -f detail

U7 Map Rendering

# Superchunk render.
titan u7 map-render STATIC/ --sc 0x55 -o superChunk_85.png

# Full world render.
titan u7 map-render STATIC/ --full -o u7_world.png

# Minimap sample with grid.
titan u7 map-sample STATIC/ --scale 4 --grid -o minimap.png

U7 map rendering combines each shape's TFA footprint with its real SHAPES.VGA frame count. Frame bit 0x20 swaps X/Y dimensions only for shapes with 32 or fewer real frames, where frames 32+ are generated reflections. Shapes with more than 32 real archive frames keep their stored dimensions. This matches current Exult behavior and fixes extended mod doors and other multi-frame objects without changing door-state or open-frame rules.

U7 World Query

# Interactive wizard — walks through shape class, flag, and area filters.
titan u7 world-query --game bg

# With explicit paths (no titan.toml required).
titan u7 world-query STATIC/ --gamedat gamedat/

# Pre-set STATIC from config, add a runtime GAMEDAT for IREG objects.
titan u7 world-query --game si --gamedat Exult/serpentisle/gamedat

The wizard prompts for shape-class checkboxes, optional shape numbers, TFA flag checkboxes, area (all or specific superchunks), and output format (summary / full text / CSV). Output can be printed or saved to a file.

U7 Container Browse

# Interactive wizard — configured BG paths.
titan u7 container-browse --game bg

# Show all chests with their full contents tree.
titan u7 container-browse STATIC/ --gamedat gamedat/ --container-name chest

# Find containers holding a sword.
titan u7 container-browse STATIC/ --gamedat gamedat/ --contains-name sword

# Export to CSV with per-frame item names (requires Exult installation).
titan u7 container-browse STATIC/ --gamedat gamedat/ -f csv -o containers.csv \
  --exult-flx "<Exult install>/data/exult_bg.flx"

# Configured paths with per-frame names from titan.toml [exult.paths].
titan u7 container-browse --game bg --container-name desk

U7 Egg Query

# Interactive wizard — configured BG paths.
titan u7 egg-query --game bg

# All usecode eggs.
titan u7 egg-query STATIC/ --gamedat gamedat/ --type usecode

# Find every placement of a specific usecode function.
titan u7 egg-query STATIC/ --gamedat gamedat/ --fn 0x06BC

# Export usecode eggs to CSV.
titan u7 egg-query STATIC/ --gamedat gamedat/ --type usecode -f csv -o usecode_eggs.csv

U8 Map Rendering

titan u8 map-render -m 5
titan u8 map-render -m 0 --no-roof
titan u8 map-render-all --maps 0 5 39 --views iso_classic iso_high

U6 World Rendering

# One surface superchunk, with world objects (furniture, items, etc.) overlaid.
titan u6 map-render -g "C:/Ultima6" --region 0,0,64,64 --objects -o chunk0.png

# A dungeon level.
titan u6 map-render -g "C:/Ultima6" --dungeon 0 --objects -o dungeon0.png

# The entire surface world.
titan u6 map-render -g "C:/Ultima6" --full -o u6_world.png

U9 Sound Extraction

# List an archive's decoded entry headers first.
titan u9 sound-list sound/Speech.flx

# Decode every supported entry to WAV (PCM, mono/stereo ADPCM, EA MicroTalk).
titan u9 sound-extract sound/Speech.flx -o speech_wav/
titan u9 sound-extract sound/sfx.flx -o sfx_wav/
titan u9 sound-extract sound/music.flx -o music_wav/

U9 3D Model Export

# Inspect a model's limb/LOD/material/texture summary first.
titan u9 model-info static/sappear.flx 2

# Export a textured OBJ (+ MTL + PNG textures) -- bitmap16.flx covers every
# real texture referenced by any model in this project's test copy of the game.
# preview.png (back-ish) + preview_front.png (rotated 180 degrees) are rendered
# alongside it automatically (needs `pip install pyvista`).
titan u9 model-export static/sappear.flx 2 -t static/bitmap16.flx -o model_2/

# Add real palette colors for any 8-bit textures instead of flat grayscale.
titan u9 model-export static/sappear.flx 2 -t static/bitmapsh.flx -p static/ankh.pal -o model_2/

# Geometry-only STL, no textures or preview needed.
titan u9 model-export static/sappear.flx 2 -f stl --no-preview -o model_2_stl/

Configuration

titan.toml stores default paths so commands can run without long path arguments. Command-line options always override config values.

Config search order:

1. ./titan.toml
2. ~/.config/titan/config.toml
3. User profile folder titan\config.toml

Use titan --config <other config.toml> <command> to override.

Minimal multi-game shape:

[u8.game]
base     = "<Ultima 8 install>"
language = "ENGLISH"

[u8.paths]
fixed    = "FIXED.DAT"
palette  = "U8PAL.PAL"
typeflag = "TYPEFLAG.DAT"
shapes   = "shapes/"
globs    = "globs/"
nonfixed = "U8SAVE.000"

[u7bg.game]
base    = "<Black Gate install>/ULTIMA7"
variant = "blackgate"

[u7bg.paths]
static  = "STATIC/"
shapes  = "STATIC/SHAPES.VGA"
palette = "STATIC/PALETTES.FLX"
gamedat = "gamedat/"

[u7si.game]
base    = "<Serpent Isle install>/SERPENT"
variant = "serpentisle"

[u7si.paths]
static  = "STATIC/"
shapes  = "STATIC/SHAPES.VGA"
palette = "STATIC/PALETTES.FLX"
gamedat = "gamedat/"

[u7si.mods."<mod-name>".paths]
root    = "<User profile>/Exult/serpentisle/mods/<mod-name>"
saves   = "<User profile>/Exult/serpentisle/mods/<mod-name>/saves"
gamedat = "<User profile>/Exult/serpentisle/mods/<mod-name>/gamedat"
archive = "<Serpent Isle install>/SERPENT/mods/<mod-name>/patch/initgame.dat"

[exult.paths]
bg_flx  = "<Exult install>/data/exult_bg.flx"
si_flx  = "<Exult install>/data/exult_si.flx"

[uo.game]
base    = "<Ultima Online Classic Client install>"

Notes:

• titan setup writes this file for you.
• U8 relative paths expand from the configured U8 install and language folder, except shapes and globs, which are local working directories.
• U7 gamedat should usually point at Exult's initialized runtime copy when available.
• U7 mod saves is discovered by scanning the mod profile root recursively for .sav files and choosing the folder with the most saves.
• A fully annotated template is available in titan.toml.example.
• Full config details are in cli_reference.md#configuration-titantoml.

Inspect the active config:

titan config
titan config --edit

Library Use

TITAN can also be imported as a Python library. U8 modules live under titan.u8; U7 modules live under titan.u7; U6 modules live under titan.u6; early U9 modules live under titan.u9. Backward-compatible imports such as from titan.shape import U8Shape are still supported.

from titan.u7.flex import U7FlexArchive
from titan.u7.palette import U7Palette
from titan.u7.shape import U7Shape

archive = U7FlexArchive.from_file("SHAPES.VGA")
shape = U7Shape.from_data(archive.get_record(150))
palette = U7Palette.from_file("PALETTES.FLX")
shape.to_pngs(palette)[0].save("shape_150_frame0.png")

Supported File Families

Game Files

TITAN requires the original game files. You must own a legitimate copy of the games. titan setup checks common GOG, EA/Origin, manual, Pentagram, ScummVM, and Exult paths.

Typical GOG, EA/Origin, manual, ScummVM/Pentagram, and Exult folders are auto-detected where possible. If setup cannot find a game, enter the game's base folder manually when prompted.

Documentation

• CLI reference
• Dialogue web README
• Annotated config template
• Font credits
• Third-party notices

Credits

TITAN uses the following excellent open-source tools:

• LeRF by Jiacheng Li, Chang Chen, et al. Adaptive downscaling and geometric transforms are powered by LeRF's official LUTs and NumPy implementation.

The font-create wizard ships six TrueType fonts for Ultima script systems. See FONTS_CREDITS.md for full attribution and licensing details.

License

MIT

TITAN also distributes a modified fold component derived from the Pentagram project as part of dialogue tooling. That component is licensed under GNU GPL v2 or later and is not covered by TITAN's MIT license.

See THIRD_PARTY_NOTICES.md and src/titan/third_party/fold/ for attribution, license scope, source mapping, build entry points, and bundled GPL license text.

Ultima (Copyright 1981-1999, Electronic Arts)

This fan-made tool requires a legitimate copy of the original games: Ultima 8 and Ultima 7. This project is not affiliated with Electronic Arts. All rights to Ultima remain with Electronic Arts.