BallWar / 领土战争 (Marble Dominion Ricochet War)

A Godot 4.6 + GDScript 2D territory-control arcade prototype — four factions fight for grid dominance in a chaotic bullet arena.
一个基于 Godot 4.6 + GDScript 的 2D 四阵营领土争夺街机原型。

Engine: Godot 4.6 · Language: GDScript · Tests: 10 runners · GitHub Actions CI · Platforms: Windows / Android

Gameplay Loop / 玩法循环

1. Four factions compete for territory on the central grid.
2. Control chambers decide firing rhythm and burst scale.
3. Turrets launch bullets into the battlefield.
4. Bullets convert cells and shift territory control.
5. Event roulette changes the match tempo.
6. A faction wins when mode-specific victory conditions are met.

Screenshots / 截图

开始界面	游戏初始	游戏中场	事件画面	胜利结果

Demo Video / GIF

• 30s gameplay loop: TODO
• event roulette demo: TODO
• save/load recovery demo: TODO
• Android layout demo: TODO

Download Latest Release / 下载最新版本

v2.1.11.1 (Latest Stable) — Windows zip · Android APK
All releases: github.com/2002yy/BallWar/releases

Tech Highlights / 技术亮点

• 10 headless CI runners — smoke, wiring, coordinator, integration, layout tests via GitHub Actions
• Architecture layering — Main.gd orchestration → coordinators, restore planners, save adapters (docs/ARCHITECTURE.md)
• Save/load with hardening — slot-based saves, backup recovery, version checks, input sanitization (docs/SAVE_SYSTEM.md)
• Performance probes — bullet pressure, frame time, trail cache metrics built into runtime (docs/PERFORMANCE.md)
• Android export pipeline — ETC2/ASTC validation, debug APK, PowerShell scripts (docs/ANDROID_EXPORT.md)
• Four-faction territory control, chamber-driven firing rhythm, event roulette, multi-mode rules

Architecture / 架构

System layering (see docs/ARCHITECTURE.md):

• Main.gd — top-level lifecycle orchestration
• SaveFlowController — continue/load flow (prepare_* / apply_*)
• RestorePlan — active restore planning data through the continue path
• SaveGameCodec + SaveStateApplier — validate, normalize, then apply
• ControlChamber, Turret, Bullet — each owns restore_from_state(...)
• Runtime-heavy: Battlefield, BulletPool, pooled trail internals

Testing / 测试

10 headless test runners run via GitHub Actions CI. Correctness baseline: 1083 checks.

Runner	Checks
LayoutSanityTestRunner.gd	376
SmokeTestRunner.gd	218
SaveFlowControllerTestRunner.gd	190
IntegrationTestRunner.gd	133
StartMenuSceneTestRunner.gd	55
GameStateCoordinatorTestRunner.gd	50
GameHUDSceneTestRunner.gd	27
EventRouletteSceneTestRunner.gd	14
RestorePlanTestRunner.gd	11
SettingsPanelSceneTestRunner.gd	9

Full guide: docs/TESTING.md

Development Setup / 开发环境

Open project.godot with Godot 4.6 in the editor.

# Headless check examples:
<godot_console> --headless --path . --script res://scripts/tests/SmokeTestRunner.gd
<godot_console> --headless --path . --script res://scripts/tests/IntegrationTestRunner.gd
<godot_console> --headless --path . --script res://scripts/tests/LayoutSanityTestRunner.gd

Release packaging: docs/RELEASE_PROCESS.md

Roadmap / 路线图

Current direction: visual & audio polish, mobile layout verification, performance baselines.
当前方向：素材与音效接入、移动端布局验证、性能基线归档。

See docs/ROADMAP.md

License / 许可

MIT License