500 A.D. - Byzantine Empire Strategy Game

A mobile-optimized turn-based strategy game set in the Byzantine Empire (Eastern Roman Empire) from 500-1453 AD.

Watch the complete gameplay walkthrough showing map navigation, unit movement, city development, and tactical combat systems:

The walkthrough demonstrates the 320x180 tile historic Byzantine-world map with accurate geography, pan controls, and fog of war revealing as you explore.

▶️ Check it online at: https://nikolareljin.github.io/500ad/

How to run this locally?

📸 Screenshots & Walkthrough

Main Menu

Leader Selection

Gameplay - Mediterranean Map

Technology & Research

Enemy Turn Processing

Overview

Command legendary Byzantine emperors and generals through pivotal moments in Eastern Roman history. Build armies, manage resources, and lead your forces to victory in historically accurate campaigns.

Features

Historical Accuracy

• 12 Playable Leaders: From Justinian I to Constantine XI Palaiologos
• 20+ Military Units: Historically accurate Byzantine forces including Cataphracts, Varangian Guard, Greek Fire, and Advanced Naval Merchant Vessels.
• Three Historical Eras: Early (500-717), Middle (717-1025), and Late (1025-1453) Byzantine periods
• Authentic Leaders: Each with unique abilities based on historical achievements
• Historic Road Network: Control major ancient trade routes including the Via Egnatia and Silk Road branches.

Massive Geographic Map

• 320x180 Tile Map: 57,600 tiles covering Europe, North/East Africa, Caucasus, Central Asia, Iran, Afghanistan, and northwestern India
• Accurate Geography: Historic-world projection from Atlantic approaches to Persia, and from Britain to the Horn of Africa
• Major Regions:
  • Western: Iberia, France, British Isles, Atlantic coast
  • Central: Italy, Balkans, Central Europe
  • Eastern: Anatolia, Caucasus, Persia, Caspian Sea
  • Southern: North Africa, Sahara, Egypt, Arabia, Red Sea
  • Northern: Ukrainian Steppe
• Realistic Terrain:
  • Water Bodies: Mediterranean (all basins), Black Sea, Caspian Sea, Red Sea, Persian Gulf
  • Mountains: Alps, Pyrenees, Caucasus, Zagros, Atlas, Taurus, Apennines
  • Deserts: Sahara, Arabian, Syrian
• Heightmap-Based: 256 elevation levels with natural color gradients
• Seeded World Generation Controls: Default historical world remains intact, with an optional procedural mode and reproducible seed/config overrides for future modding
• Fog of War: Discover the world as you explore with your units
• Layered Visibility Model: Unexplored terrain, explored shroud, and currently visible tiles are now rendered separately

Gameplay

• Turn-Based Strategy: Tactical combat with resource management
• Infrastructure System: Recruit Engineers to build a permanent road network, improving travel speed between your cities.
• Naval Transport: Embark land units onto Transports and Merchant Ships to cross the Mediterranean.
• Technology Tree: Open a tiered research tree with prerequisites, multi-turn research time, and explicit lock/available/researching/researched states.
• Research Progression: Run one active research project at a time; costs are paid when started and completion happens over subsequent turns.
• Tech Unlock Integration: Technologies now unlock specific units, city buildings, and infrastructure actions while also feeding combat, economy, and diplomacy bonuses.
• City Building Tree: Develop each city through upgradeable Farms, Barracks, Mines, Workshops, Temple, and Walls, each with tech requirements and build times.
• Command Overview Panels: A modular side rail summarizes resources, faction intel, city-management pressure, and active events with contextual tooltips and quick actions.
• Pan Navigation: Drag to explore the massive map
• Top Minimap Navigation: View the full world and jump to any region with click/drag
• Unit Progression: Experience and leveling system with role-based stat growth and veteran promotions along upgrade paths
• Training Queue System: Recruitment now uses per-city training time and queue processing each turn
• Combat System: Tactical layer with formations (Line, Wedge, Shield Wall), battle-type/terrain modifiers, effective morale-driven outcomes, and concise combat logs
• AI Factions with Personalities: Enemy realms act by faction identity and personality archetype (aggressive, defensive, opportunistic, diplomatic) with different expansion/warfare/resource priorities
• Diplomacy & Trade System: Negotiate truces, alliances, trade agreements, and declarations of war with per-faction trust/hostility and reputation impacts
• Trade Routes: Active agreements create income routes that can be raided/disrupted by hostile pressure and war outcomes
• Quest & Dynamic Events: Turn-based narrative system that triggers quests/events from time, location pressure, diplomacy status, resources, and player progress; each event has branching choices with lasting consequences
• Tutorial & Onboarding: Guided early-game onboarding for movement, combat, city building, diplomacy, and turn flow with contextual hints, skip support, and replay from the in-game menu
• Unit Vitality UI: Recently damaged units show a map health ring (green -> red) to highlight their current health
• Fortification System: Any unit can fortify and build a permanent defensive fort on its tile
• Healing System: Recover in towns, while fortified, or from adjacent support/healer units
• Resource Management: Gold, manpower, prestige, and strategic stockpiles (food, wood, stone, iron, rare materials)
• Strategic Resource Distribution: Terrain/biome-based deposits are placed across the map and contribute to nearby city output
• Terrain Effects: Terrain now affects movement, combat effectiveness, and city build suitability (farms, irrigation, canals, forest management)
• Biome Rules: Deterministic biomes (plains, forest, desert, mountains, tundra) influence movement costs, strategic resource weighting, and event-affinity metadata used by dynamic events
• Save/Load System: Multiple save slots with auto-save
• Versioned Save Schema: Save files are stored as versioned JSON envelopes with legacy-save normalization for smoother compatibility across releases
• Exploration: Fog of war reveals as units move and cities are founded
• Vision & Recon Rules: Unit classes and city status determine sight radius (scouts/intel see farther; capitals/fortified cities project wider vision)
• Exploration Discoveries: Finding new macro-regions and landmark cities triggers discovery events with gold/manpower/prestige rewards
• Auto Explore Units: Explorer and Merchant Galley support automated exploration to continuously uncover map fog
• Dynamic Enemy Realms: AI factions maintain territory pressure, diplomacy/threat memory (AI-side), and strategic reactions to player captures and frontier changes

Mobile Optimized

• Touch Controls: Tap to select, drag to pan, and double-tap a selected unit to arm/disarm move mode
• Responsive Design: Works on phones and tablets
• Performance Optimized: Render queueing, fog alpha caching, and viewport-based drawing tuned for the 57,600-tile map
• Portrait & Landscape: Supports both orientations
• Compact Mobile Unit Panel: Unit details now appear in a reduced bottom panel so map interactions stay accessible during unit control

How to Play

Starting the Game

1. Run ./run
2. Select "New Campaign" from the main menu
3. Choose your era (Early, Middle, or Late Byzantine)
4. Select a leader
5. Begin your campaign!

Note: the opening position and controlled towns depend on the selected era, leader, and scenario (including enemy-side campaigns).

Controls

• Tap/Click: Select units or tiles
• Drag Map: Pan around the historic world map to explore
• Minimap Click/Drag: Reposition the camera quickly to any world area
• Tap/Click Unit: View unit details
• Double-Click / Double-Tap Selected Unit: Toggle Move Mode ON/OFF
• With Move Mode ON: Tap/click a destination tile to issue the movement order
• Tap/Click the Selected Unit Again: Cancel move mode quickly (Move Mode OFF)
• End Turn Button: Complete your turn and generate resources
• Research Button: Open the technology tree, inspect prerequisites/unlocks, and start new projects when no research is active
• Tutorial & Onboarding: Follow the guided panel in early turns; skip anytime or replay from Game Menu -> Tutorial & Onboarding

Map Navigation

• Pan: Click and drag anywhere on the map to move your view
• Minimap: Top HUD minimap shows the entire world with current viewport highlighted
• Fast Travel: Click or drag on the minimap to jump the visible map section
• Explore: Move units to reveal fog of war
• Position: Current map coordinates shown in top-left corner
• Campaign Focus: Map starts centered on your selected leader's starting realm (or field army for nomadic starts)

Resources

• Gold 💰: Used to recruit units and construct buildings
• Manpower 👥: Required to recruit military units
• Prestige ⭐: Earned through victories and achievements
• Food 🌾: Generated by city agriculture plus fertile/resource-rich hinterlands
• Wood 🪵: Gathered from nearby forests and supports industrial growth
• Stone 🪨: Sourced from hills/mountains and improves fortification potential
• Iron ⛓️: Sourced from mineral-rich terrain and boosts advanced industry output
• Rare Materials 💎: Trade-oriented luxury/strategic resources from special regions

Terrain & Resource Effects

• Biome-weighted resources: Plains and river basins favor food, forests favor wood, hills/mountains favor stone/iron, and coastal/special zones can produce rare materials.
• Movement penalties/bonuses: Units still use class-based movement rules, but terrain effects now provide a shared base for movement cost adjustments.
• Combat terrain consistency: Combat terrain modifiers now use the same terrain-effect definitions used by movement/build systems.
• Build restrictions by terrain:
  • Build Farm requires fertile/river/coastal land nearby
  • Irrigate requires river/coast/fertile lowland access
  • Build Canal requires coast or river access
  • Plant Forest requires suitable nearby land
• City production footprint: Cities benefit from surrounding terrain and nearby strategic deposits rather than only the city tile itself.

Combat

• Units have different strengths against infantry, cavalry, or buildings
• Terrain provides defensive bonuses
• Morale affects combat effectiveness
• Units gain experience and level up

Byzantine Leaders

Early Byzantine (500-717 AD)

• Justinian I "The Great": Reconquest specialist, +20% siege damage
• Belisarius: Legendary general, +30% cavalry power
• Narses: Infantry master, +25% infantry defense
• Heraclius: Reformer, +20% manpower regeneration

Middle Byzantine (717-1025 AD)

• Leo III "The Isaurian": Fortification expert, +40% defense
• Basil II "Bulgar-Slayer": Relentless conqueror, +25% attack
• Nikephoros II Phokas: Heavy cavalry master, +35% cataphract power
• John I Tzimiskes: Rapid deployment, +40% movement speed

Late Byzantine (1025-1453 AD)

• Alexios I Komnenos: Diplomatic genius, -30% mercenary costs
• Manuel I Komnenos: Naval supremacy, +40% naval power
• Constantine XI Palaiologos: Heroic defender, +50% defense when outnumbered
• Michael VIII Palaiologos: Reconqueror, +25% when recapturing territories

Military Units

Infantry

• Skutatoi: Heavy infantry with large shields
• Psilos: Light skirmishers
• Byzantine Archers: Composite bow specialists
• Varangian Guard: Elite Norse axe warriors

Cavalry

• Cataphracts: Super-heavy armored cavalry (signature unit)
• Klibanophoroi: Ultra-heavy cavalry
• Kavallarioi: Medium cavalry backbone
• Horse Archers: Light cavalry with bows
• Tagmata: Elite professional cavalry

Special & Naval Units

• Engineer Unit: Specialized non-combat unit for building roads and improving city infrastructure
• Merchant Galley: Large transport capable of carrying 3 land units with trade bonuses
• Greek Fire Dromon: Elite warship equipped with the deadly Greek Fire siphon for ship-to-ship and siege combat
• Transport Ship: Basic naval transport for moving troops across seas
• Greek Fire Siphon: Devastating incendiary weapon for land sieges
• Siege Engineers: Fortification specialists
• Orthodox Priests: Morale and healing support
• Field Healer: Dedicated battlefield medical unit with strong adjacent healing

Technical Details

Technologies Used

• HTML5 Canvas for map rendering
• Vanilla JavaScript (no frameworks)
• CSS3 with Byzantine-themed design
• LocalStorage for save/load
• Versioned JSON save envelope (schemaVersion, format, metadata, payload)
• Web Audio API for sound

File Structure

500ad/
├── index.html          # Main entry point
├── run                 # Starts local server + opens browser
├── script/             # Compatibility utility wrappers
├── scripts/
│   ├── update.sh       # Updates/pins script-helpers submodule
│   ├── runner.sh       # Runtime launcher for local play
│   └── script-helpers/ # Git submodule (branch: production)
├── css/                # Stylesheets
│   ├── main.css       # Core design system
│   ├── ui.css         # UI components
│   └── mobile.css     # Mobile optimizations
├── js/                 # Game logic
│   ├── game.js        # Main controller
│   ├── state.js       # State management
│   ├── leaders.js     # Leader data
│   ├── units.js       # Unit data
│   ├── combat.js      # Combat system
│   ├── map.js         # Map rendering
│   ├── ui.js          # UI controller
│   ├── audio.js       # Audio manager
│   └── storage.js     # Save/load system
├── assets/            # Graphics and data
│   ├── geography.js   # Polygon-driven historic theater heightmap
│   ├── favicon.svg    # Byzantine four-beta cross icon
│   ├── symbols.js     # Byzantine symbols
│   ├── images/
│   └── audio/
└── docs/              # Documentation
    ├── geography.md   # Geography model and coordinate system
    ├── gameplay-systems.md # Unit health, healing, and fortifications
    └── media/         # Screenshots and videos

Map Coordinates Reference

Key historical cities on the 320x180 map:

• Constantinople (Byzantine Capital): positioned from real lat/lon (28.97E, 41.01N)
• Rome (Western Capital): positioned from real lat/lon (12.50E, 41.90N)
• Alexandria (Egypt): positioned from real lat/lon (29.92E, 31.20N)
• Baghdad (Abbasid Capital): positioned from real lat/lon (44.37E, 33.31N)
• Jerusalem (Holy City): positioned from real lat/lon (35.22E, 31.78N)
• Mecca / Medina (Arabian Peninsula): positioned from real lat/lon
• Axum / Adulis (Ethiopia-Horn region): positioned from real lat/lon

Browser Compatibility

• Chrome/Edge (recommended)
• Firefox
• Safari
• Mobile browsers (Chrome, Firefox, Safari)

Running Locally

One-Liner (Clone + Run)

Copy/paste one of these commands:

• Linux/Mac:

curl -fsSL https://raw.githubusercontent.com/nikolareljin/500ad/main/scripts/quickstart.sh | bash

• Windows:

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/nikolareljin/500ad/main/scripts/quickstart.ps1 | iex"

This will:

1. Clone 500ad to ~/500ad (or update it if already cloned)
2. Run ./run automatically

Quick Start (Recommended)

./run

This starts a local server, opens the browser automatically, and runs scripts/update.sh first if scripts/script-helpers is not installed.

Update Helpers Submodule

./scripts/update.sh

Version Management (Single Source of Truth)

• VERSION is the canonical release version used for checks and tagging.
• Set/sync a new version:

./scripts/version_set.sh 1.12.0

• Verify version consistency:

./scripts/check_release_version.sh

• Create annotated release tag from VERSION:

./scripts/tag_release.sh

With Local Server (Recommended)

cd 500ad
python3 -m http.server 8000

Then open http://localhost:8000 in your browser

On Mobile Device

1. Start local server on your computer
2. Find your computer's local IP address
3. On mobile, navigate to http://[YOUR_IP]:8000

Development

Adding New Leaders

Edit js/leaders.js and add leader data following the existing format.

Adding New Units

Edit js/units.js and add unit types with stats and bonuses.

Customizing Appearance

Modify CSS variables in css/main.css to change colors and styling.

Geography and City Coordinates

See docs/geography.md for:

• map bounds and projection
• land/sea generation approach
• seeded biome/resource generation and modding parameters
• how city lon/lat values map to 320x180 tile coordinates

World Generation Modding (Advanced)

• The default map mode is historical (heightmap + historic towns/roads), but you can switch to a seeded procedural terrain mode for testing/modding.
• Inspect current generation config in the browser console:

window.getWorldGenerationConfig()

• Apply overrides and regenerate the map:

window.setWorldGenerationConfig({
  mode: 'procedural',
  seed: 'issue-8-demo',
  terrain: { seaLevel: 0.34, mountainThreshold: 0.79 },
  climate: { desertHumidityThreshold: 0.34 }
})

• setWorldGenerationConfig(...) regenerates the entire map (terrain, cities, roads, resources). It is intended for pre-game/testing use; active-session regeneration is blocked by default to avoid partial state resets.
• Procedural mode currently does not generate procedural rivers yet, so river/fertility bonuses still follow the historical heightmap river data path.
• Procedural regeneration can take noticeable time on slower devices because terrain/biome noise is recomputed across the full map.
• Save/load compatibility for procedural worlds assumes compatible generation rules; changing generation code between versions can alter regenerated terrain/resource layouts for the same seed.
• Legacy save slots are normalized to the current save envelope format during load/import to keep save metadata and payload shape consistent.
• These APIs are intended for trusted local modding/testing scripts only. Do not run untrusted browser-console snippets.
• Biome event-affinity metadata is exposed on map tiles as tile.biomeEventWeights and is consumed by the dynamic event pipeline.

Quests & Dynamic Events

• Open the Quests action from the bottom action bar to review active quests/events and history.
• New quest/event opportunities are generated during turn processing from:
  • time progression milestones
  • frontier/location pressure
  • faction relations and diplomacy status
  • resource shortages/surpluses
  • recent player progress (for example city captures)
• Each quest/event has branching choices with resource/diplomacy consequences.
• Resolved and expired entries are stored in a persistent history log and saved with the campaign.

AI Faction Behavior (Current Scope)

• Enemy forces are still represented as owner: enemy, but now coordinate by unit.faction / city faction identity.
• AI personalities influence whether factions prioritize expansion, defense, opportunistic attacks, or resource investment.
• Diplomacy is now player-driven through the Diplomacy panel and still feeds AI-side hostility/targeting decisions.
• AI reactions are driven by world-state events such as city captures and changing frontier pressure.

Historical Notes

The Byzantine Empire, also known as the Eastern Roman Empire, lasted from 330 AD (founding of Constantinople) to 1453 AD (Fall of Constantinople). This game focuses on the period from 500-1453 AD, covering:

• Justinian's Reconquest (527-565): Attempt to restore the Roman Empire
• Arab Invasions (7th-8th centuries): Defense against Islamic expansion
• Macedonian Renaissance (9th-11th centuries): Byzantine golden age
• Crusades (11th-13th centuries): Complex relations with Western Europe
• Ottoman Conquest (14th-15th centuries): Final struggle for survival

All leaders, units, and historical events are based on actual Byzantine history.

Credits

• Game Design & Development: AI-assisted development
• Historical Research: Based on Byzantine military history
• Art Style: Byzantine mosaic and icon art inspiration
• Leader Portraits: AI-generated historical artwork

Version

Version 1.20.0 - Introduces a data-driven modding system: players can load JSON mods that add custom units, buildings, technologies, and event-driven quests, with three pre-packaged example mods (Greek Fire Refinement, Barbarian Auxiliaries, Imperial Roads Expansion) shipped out of the box.

License

This is a historical educational game. All historical figures and events are in the public domain.

---

For the Glory of Constantinople! ⚔️👑

---

Clone traffic

Updated daily. Total and unique cloners over the last 14 days.