A compact, data-driven 3D battlefield engine powered by Three.js, enabling historical battle simulation through parameterized terrain, multi-faction support, and live editing – all in a single HTML file.
Battlefield Editor is a lightweight, browser-hosted 3D engine tailored for historians, strategy enthusiasts, and AI developers interested in reconstructing and experimenting with historical battles. The entire application runs from a single HTML file, making it highly portable and straightforward to distribute. Each battle scenario exists as a self-contained data package – included examples cover the Battles of Red Cliffs, Guandu, Gaixia, and Feishui.
What distinguishes this tool is its data-driven foundation. Rather than embedding terrain or unit logic directly in code, the engine interprets a six-layer data schema that defines analog terrain, declarative effects, an audio vocabulary, and faction configurations. This design lets users swap entire battle scenarios by loading a different package, while an integrated AI authoring loop enables iterative scenario generation and refinement.
- Single-file data-driven 3D engine – The entire battlefield simulation runs from one HTML file with zero server dependencies
- Parameterized analog terrain – Elevation, vegetation, and obstacles are defined through data layers instead of manual modeling
- Declarative effects and audio vocabulary – Explosions, weather, and soundscapes are described using straightforward configuration syntax
- Multi-faction support – Opposing armies, their units, and behaviors are independently configurable
- Replaceable glTF models – Custom 3D assets can be swapped in using the standard glTF format
- Real-time editor mode – Battle parameters can be modified live with immediate visual feedback
- Six-layer data schema – A structured data model covering terrain, units, effects, audio, factions, and metadata
- AI authoring loop – Battle scenarios can be generated and refined through iterative AI-assisted design
- Clone the repository or grab the single HTML file:
git clone https://github.com/reedryan65/battlefield-editor-loader.git
- Open
index.htmldirectly in any modern browser (Chrome, Firefox, Edge, Safari) - No build tools, package managers, or server are needed
- Launch the editor – Open
index.htmlin your browser - Load a battle package – Pick from built-in scenarios (Red Cliffs, Guandu, Gaixia, Feishui) or import your own
- Explore the battlefield – Use mouse controls to orbit, pan, and zoom within the 3D scene
- Edit in real time – Activate editor mode to adjust terrain parameters, unit positions, or effect settings
- Export your scenario – Save your modified battle as a new package for sharing
Example workflow:
# Open the editor
open index.html
# In the interface:
# 1. Click "Load Package" → Select "chibi.json" (Red Cliffs)
# 2. Use editor panel to adjust terrain roughness
# 3. Click "Export" to save your custom versionAll settings reside within battle package files (JSON format). The engine reads a six-layer schema:
- Terrain layer – Elevation map, ground textures, obstacles
- Unit layer – Faction assignments, unit types, formations
- Effects layer – Weather, fire, smoke, particle systems
- Audio layer – Ambient sounds, battle cries, impact effects
- Faction layer – Army colors, banners, AI behavior parameters
- Metadata layer – Battle name, historical context, version info
To customize default behavior, edit the relevant JSON fields in your battle package or use the in-editor interface.
- Platform: Any modern web browser (Chrome 90+, Firefox 88+, Edge 90+, Safari 14+)
- Runtime: No server required – runs entirely client-side
- Storage: ~5 MB for the engine file; battle packages range from 50 KB to 2 MB each
- Hardware: WebGL-capable GPU recommended for smooth 3D rendering
- Network: Internet connection only needed for loading external glTF models
How do I update the engine?
Simply download the latest HTML file from the repository. Your battle packages remain compatible across versions.
Can I add my own 3D models?
Yes. The engine supports glTF format. Place your model files alongside the HTML file and reference them in your battle package configuration.
Does it work offline?
Absolutely. Once downloaded, the single HTML file runs completely offline with no server communication.
How do I create a new battle scenario?
Use the editor mode to design your battlefield, then export the package. Alternatively, write a JSON file following the six-layer schema manually.
What if I encounter a visual glitch?
Try disabling hardware acceleration in your browser or updating your graphics drivers. Most issues are related to WebGL compatibility.
GNU GPL v3.0 – see LICENSE for details.