mosul is the public Mac SwiftUI interface and project home for a tactical war game and playable demo set in Mosul, Iraq. The first demo target is the 2003 Market / Commercial Streets scenario: a tense post-invasion urban security fight built around patrols, checkpoints, shopfronts, rooftops, civilians, looting pressure, raids, hidden weapons, and sudden close-range contact.
The aim is not to make a generic arena shooter with a Mosul label. The project is about a city: streets, roofs, courtyards, alleys, civic buildings, market lanes, civilians, military uncertainty, and the uncomfortable transition from battlefield victory to public security.
The initial playable scenario is centered on the 2003 U.S. presence in Mosul after the city fell during Operation Iraqi Freedom. The baseline allied identity is U.S. Army conventional infantry associated with the 101st Airborne Division period in Mosul, with local security problems and early disorder rather than the later 2016-2017 ISIS siege model.
The demo combat space is a 500 m x 500 m Market / Commercial Streets cluster. The current source overview is a 7,000 px x 7,000 px black-and-white line-art map, about 14 px per meter, with the full combat art target still expected to scale toward about 70 px per meter.
The map is designed for multi-layer play. Ground streets, courtyards, shopfronts, and building interiors need to coexist with rooftop movement, upper-floor fire, stair access, breach points, rubble, blocked roads, and changing cover. The engine work is expected to support streamed map tiles rather than one enormous always-loaded bitmap.
The current engine scenario now loads from validated data in the modernerKrieg submodule instead of only from hard-coded C fixtures. The first public scenario file is:
modernerKrieg/game/mosul/scenarios/market_commercial_streets_2003.mkscenario
The matching map, sprite, and marker manifests are also present under:
modernerKrieg/assets/mosul/manifests/
The native Mac demo is now present in this repository as MosulGame.xcodeproj, with the earlier Mosul.xcodeproj wrapper retained for continuity. MosulGame is a thin SwiftUI app over the modernerKrieg C core: SwiftUI handles presentation and input, a small C bridge exposes the current scenario state to Swift, and the simulation, AI, scenario data, manifest parsing, and PNG runtime assets remain in the submodule.
The current Mac app renders the runtime Market / Commercial Streets ground-level PNG plus upper-floor and roof-access alpha overlays from modernerKrieg/assets/mosul/runtime/, receives the sprite, marker, map-level, unit-level, contact-level, and interaction-level ids it needs through the C bridge, draws matching runtime PNG sprites from modernerKrieg, overlays edge-aware tactical markers for objectives, orders, routes, suppression, casualties, civilians, dedicated civilian-risk underlays, clustered contact reports, and breach/search/cache/rooftop interactions, labels selected-unit/contact/interaction level context, auto-shows tactically referenced upper-floor overlays, shows C-core after-action results in the inspector, and provides controls for side selection, selection, movement, investigation, breach/search, map-level visibility, single-step simulation, reset, and deterministic opponent AI ticks.
The Mac app also includes the codenamed snapshot path for visual testing. The Snapshot command renders the current tactical map to timestamped PNG files in the local snapshots/ directory, which is ignored by git, so interesting battle states and civilian-risk moments can be kept as throwaway visual evidence during development. For repeatable visual evidence, run:
scripts/capture_snapshot_evidence.shThat command builds the Mosul app, runs a deterministic snapshot-only launch, and writes snapshots/evidence/mosul-map-evidence.png for before/after comparison.
MOSUL is commanded at unit scale, but it should preserve meaningful detail inside units. A squad should not be just one counter with a hit point number. Soldiers need roles, weapons, ammo, wounds, suppression, stance, exposure, and equipment. A medic, breacher, automatic rifleman, marksman, squad leader, vehicle crew, or RPG gunner should change the tactical problem.
The first demo side lists are intentionally compact:
- U.S. / coalition / local security: rifleman, squad leader, automatic rifleman, grenadier, marksman, medic, engineer / breacher, and Humvee / vehicle crew.
- Regime remnant / disorder / early insurgent force: rifleman, irregular fighter, cell rifleman, RPG gunner, machine gunner, sniper / marksman, mortar or rocket harassment cell, and weapons looter / armed criminal.
Combat should be about more than direct fire. The important systems are line of sight, suppression, morale, casualties, civilian risk, rooftop access, breach/entry actions, hidden defenders, IED suspicion, vehicle vulnerability, smoke, rubble, route clearance, medical recovery, and whether a cleared street stays cleared.
The 2003 demo starts with a restrained weapons set: rifles, carbines, squad automatic weapons, grenade launchers, machine guns, RPGs, marksman rifles, mortars or off-map harassment, vehicle weapons, smoke, and breaching tools. Heavy support should matter, but it should not erase the urban problem.
Vehicles are tactical tools rather than scenery. Humvees, trucks, armored vehicles, technicals, engineering vehicles, and air-support markers all need to interact with streets, rubble, rooftops, ambush angles, civilian movement, and extraction routes.
All public presentation art should stay in contemporary black-and-white graphite line art: dense drafted linework, varied stroke weight, hatching, realistic silhouettes, and believable tactical detail. Stick figures, stick weapons, bare schematic blocks, and placeholder programmer art do not belong in public graphics.
The top-down sprites are also line-art assets. The current tactical scale uses 128 x 128 combatant cells. Movement and casualty states should be represented through body position and silhouette: standing, crouch, prone, wounded, and dead, with renderer flips deriving additional facings where possible.
Civilian sprites are part of the tactical system rather than background decoration. The current non-combatant set includes old man, old woman, adult woman, teenage boy, teenage girl, young girl, and young boy archetypes, each with standing, wounded, and dead non-graphic body states plus eight runtime facings.
The modernerKrieg submodule now includes a larger runtime asset base: complete source-angle infantry, civilian, weapon, and vehicle sprites, 1,064 rendered runtime-facing PNGs, a runtime map overview for the Market / Commercial Streets scenario, and validated C-readable manifests for map, sprite, and marker metadata. Source art remains preserved separately from generated/runtime assets.
The engine work lives in the modernerKrieg submodule. It is now a portable C + CMake tactical engine with validated data loading, asset-manifest parsing, deterministic AI/autoplay tools, replay validation, renderer-independent board projection, and PNG-backed runtime asset handoff for native frontends.
See PLAN.md for the playable-demo development plan.
The SDL experiment has been removed from the active engine path. Launchable interfaces should now be platform-native shells over the same portable C libraries. The Mac shell lives here in mosul; modernerKrieg remains the owner of all C core behavior, loaders, manifests, command-line tools, replay validation, and runtime PNG assets. The command-line tools remain the deterministic testing, replay, and balancing surface.
To inspect or build the engine:
git submodule update --init --recursive
cd modernerKrieg
cmake --preset headless
cmake --build --preset headless
ctest --preset headlessRun the current headless smoke scenario:
./build/headless/bin/mk_headless_run --steps 10Run both tactical sides under deterministic AI:
./build/headless/bin/mk_headless_run --ai-only --max-ticks 10Write and validate a deterministic replay:
./build/headless/bin/mk_headless_run \
--ai-only \
--max-ticks 10 \
--quiet \
--replay build/headless/mosul_ai.mkreplay
./build/headless/bin/mk_replay_validate \
--expect-result MK_OK \
build/headless/mosul_ai.mkreplayThe current headless CTest suite validates the portable core, board-view projection, fixed loop, AI behavior, asset manifests, scenario data, headless runs, replay output, balance checks, and core/frontend boundary.
The Mac app source is kept in mosul, not in modernerKrieg:
MosulGame.xcodeproj: Xcode project for the player-facing native Mac game.Mosul.xcodeproj: earlier native Mac wrapper retained for continuity.Mac/Mosul/App/: SwiftUI app, map view, controls, and inspector panels.Mac/Mosul/Bridge/: C bridge between Swift and themodernerKriegheaders.Mac/README.md: Mac-specific build notes.
Open the player-facing project from the repository root:
open MosulGame.xcodeprojOr build the current debug game from Terminal:
xcodebuild -project MosulGame.xcodeproj \
-scheme MosulGame \
-configuration Debug \
-derivedDataPath build/MosulGameDerivedData \
buildRun the repeatable native Mac smoke path:
scripts/run_mac_smoke.shThe smoke script builds MosulGame.xcodeproj, Mosul.xcodeproj, and AIBattle.xcodeproj into build/mac-smoke/ through Xcode, with code signing disabled, then verifies that each expected .app executable was produced. The root Mac App Smoke GitHub Actions workflow runs the same script on macOS, complementing the portable CTest coverage in modernerKrieg.
The app expects the submodule at mosul/modernerKrieg. It loads the current .mkscenario file, map manifest, runtime map level PNGs, and overview fallback directly from that submodule during development, so PNG files and loaders do not need to be copied into the Mac app tree.
MosulGame starts by letting the player command either the U.S. patrol or the opposing armed cell in the decisive 2003 Market / Commercial Streets battle. The chosen side receives manual orders while the opponent advances through the same deterministic tactical AI used by AIBattle.
The standalone AIBattle.xcodeproj app is an AI-vs-AI autoplay shell over the same shared Mosul Swift model, tactical map view, C bridge, and modernerKrieg core sources. It continuously runs both sides under AI, visualizes battle state, records each result, and restarts with the next seeded battle variant so playability and visualization can be exercised before the main player-facing app is complete.
AIBattle also has a repeatable evidence path for pacing and readability review:
scripts/capture_aibattle_evidence.shThat command builds AIBattle, runs a deterministic evidence-only launch, and writes snapshots/evidence/aibattle-evidence.png plus snapshots/evidence/aibattle-evidence.txt with the first tuning target, result pressure, and partial-settlement state identified from the sample.
AIBattle can also export a full-battle movie with the tactical map, markers, score, civilian state, unit state, contacts, tuning status, and final result visible in every frame:
scripts/capture_aibattle_movie.shThat command builds AIBattle, runs its deterministic movie-only launch, and writes snapshots/evidence/aibattle-battle-1.mov plus a matching .txt report. Use --battle-index, --fps, --output, and --report to create shareable variants for external developer review.
xcodebuild -project AIBattle.xcodeproj \
-scheme AIBattle \
-configuration Debug \
-derivedDataPath build/AIBattleDerivedData \
buildMOSUL follows lessons from earlier work rather than starting from a blank page. guderian and its included derZweiteWeltkrieg engine provide useful design memory: deterministic C rules, headless tests, a thin presentation layer, scenario boards, morale, movement, fire, objectives, and a practical SwiftUI app path.
MOSUL is not a reskin of a World War II system. Modern Mosul needs its own rules for civilians, asymmetric threats, rooftop movement, hidden positions, drones, IED suspicion, civilian-harm scoring, vehicle exposure, breach actions, and post-combat security. The legacy is engineering discipline, not era reuse.
mosul/
MosulGame.xcodeproj/ native Mac player-facing game project
Mosul.xcodeproj/ native Mac demo project
AIBattle.xcodeproj/ native Mac AI-vs-AI autoplay project
README.md
Mac/ SwiftUI app and C bridge
assets/readme/ public README artwork
modernerKrieg/ tactical engine, data, tools, and runtime assets
Important modernerKrieg paths:
engine/core/: portable simulation, rules, state, scoring, and replay-facing data.engine/render/: renderer-independent board and overlay projection.engine/assets/: portable map, sprite, and marker manifest parsing/validation.engine/ai/: deterministic controller policies that emit normal core orders.engine/tools/autoplay/: headless run, replay validation/playback, and AI-vs-AI tools.game/mosul/scenarios/: validated Mosul scenario data.assets/mosul/source/: unmodified source art and map assets.assets/mosul/runtime/: generated or copied runtime products, including the current map overview and rendered sprites.assets/mosul/manifests/: map, sprite, and marker manifests validated by C tests.
Source art should remain unmodified. Engine-ready sprites, atlases, tiles, collision data, and runtime map products should be generated from source assets rather than edited directly in place.
The public face of development is the Guderian Discord server:
Join the Guderian Discord server
Interested users, testers, artists, historians, engineers, and potential developers can also contact:
barbalet at gmail dot com
See LICENSE.