magicciv/tools/transpile-engine

Engine Transpiler

GDScript to TypeScript transpiler for the Magic Civilization web guide. Reads GDScript game engine sources and produces two auto-generated TypeScript files consumed by the @magic-civ/engine-ts package.

Output Files

Generated File	Purpose	GDScript Sources
ClimatePhysics.generated.ts	Per-turn climate simulation engine	climate.gd, climate_base.gd, ecological_events.gd, anchor_decay.gd, climate_spec_eval.gd
MapGenerator.generated.ts	9-stage procedural map generation pipeline	map_generator.gd, map_shape_seeds.gd, terrain_refiner.gd, wind_calculator.gd, hydrology.gd, hydrology_rivers.gd, hex_utils.gd

Both files are written to packages/engine-ts/src/.

Usage

# Generate both files
uv run tools/transpile-engine/transpile.py

# CI check — exits 1 if either generated file is stale vs GDScript source
uv run tools/transpile-engine/transpile.py --check

uv handles dependency resolution automatically from the inline script metadata (no manual pip install needed).

Dependencies

• Python: >= 3.11
• lilith-gdscript-transpiler: >= 1.1.0 (from Forgejo PyPI at forge.nasty.sh)

The transpiler package provides:

• Transpiler / TranspilerConfig — high-level runner with staleness checking
• extract_functions() — parses GDScript source into function body dict
• transform_method_body() — line-by-line GDScript to TypeScript conversion
• PCG32_PREAMBLE — TypeScript PCG32 PRNG class (bit-identical to Godot 4's RandomNumberGenerator)

Architecture

Climate transpiler (transpile.py): Uses transform_method_body() for most physics methods (temperature, moisture, corruption, etc.) with hand-written sections for complex subsystems (ecological events, aerosol forcing).

Map generator transpiler (mapgen_assembly.py): Hand-written TypeScript that faithfully implements the GDScript 9-stage pipeline. The structural transformation from GDScript's axial-keyed Dictionary maps to TypeScript's flat TileState[] array (via an internal GenMap class during generation) requires architectural changes beyond line-by-line transpilation.

Source File Locations

Climate (in engine/src/modules/climate/)

• climate.gd — main simulation orchestrator
• climate_base.gd — temperature, moisture, terrain evolution base methods
• ecological_events.gd — stochastic geological/ecological events
• anchor_decay.gd — ley anchor strength decay
• climate_spec_eval.gd — spec condition evaluator

Map Generation (in engine/src/generation/)

• map_generator.gd — 9-stage pipeline orchestrator
• map_shape_seeds.gd — region seed shapes + terrain classification
• terrain_refiner.gd — coastlines, relief, patches, quality
• wind_calculator.gd — 3-cell wind model
• hydrology.gd — Planchon-Darboux depression fill, flow accumulation
• hydrology_rivers.gd — lakes, rivers, deltas, sources

Hex Utilities (in engine/src/map/)

• hex_utils.gd — coordinate conversions, neighbor lookup (used by map gen)