kms-ux/wanderingquantum

Purpose and Runtime

This is a native Android/Kotlin pixel-art life-simulation/adventure game. Its architecture combines a game loop, deterministic/procedural world generation, player progression systems, sprite-based rendering, and Android UI integration. The Gradle Android app is rooted at app/build.gradle.kts; Android packaging and activity registration are in app/src/main/AndroidManifest.xml.

Entry Points and Composition

Android starts through app/src/main/java/com/wanderingquantum/MainActivity.kt. Game-side startup is represented by app/src/main/kotlin/com/wanderingquantum/Main.kt, which likely composes the engine, world, player, and UI layers. Shared engine models define cross-system contracts in app/src/main/kotlin/com/wanderingquantum/model/EngineTypes.kt and domain types for mines, NPCs, and quests.

Core Engine and Simulation State

The engine layer owns global game concerns: timing, events, saves, configuration, and seeded randomness:

• app/src/main/kotlin/com/wanderingquantum/engine/TimeEngine.kt

• app/src/main/kotlin/com/wanderingquantum/engine/EventBus.kt

• app/src/main/kotlin/com/wanderingquantum/engine/SaveSystem.kt

• app/src/main/kotlin/com/wanderingquantum/engine/SeedMatrix.kt

Control should flow from input/time updates into gameplay systems, with EventBus serving as the decoupling boundary for state changes and reactions. SaveSystem is the persistence boundary between runtime game state and device storage; no server-side infrastructure is evident.

World Construction and Procedural Generation

The world layer manages maps, zones, and game-content registries:

• app/src/main/kotlin/com/wanderingquantum/world/TileMap.kt

• app/src/main/kotlin/com/wanderingquantum/world/ZoneManager.kt

• app/src/main/kotlin/com/wanderingquantum/world/Registries.kt

Generation algorithms are isolated under world/procedural, including cellular automata and wave-function-collapse generation in app/src/main/kotlin/com/wanderingquantum/world/procedural/CellularAutomataGenerator.kt and app/src/main/kotlin/com/wanderingquantum/world/procedural/WfcMapGenerator.kt. These consume seed/trait inputs and produce map or zone state that rendering and simulation consume.

Player and Gameplay Systems

Player state, inventory, and movement/control are separated in:

• app/src/main/kotlin/com/wanderingquantum/player/Player.kt

• app/src/main/kotlin/com/wanderingquantum/player/Inventory.kt

• app/src/main/kotlin/com/wanderingquantum/player/PlayerController.kt

Feature systems implement domain actions and progression, notably mining, NPC/quest interaction, combat, economy, crafting, and relationships. Architecturally central coordinators include app/src/main/kotlin/com/wanderingquantum/systems/MineSystem.kt, app/src/main/kotlin/com/wanderingquantum/systems/NPCManager.kt, and app/src/main/kotlin/com/wanderingquantum/systems/QuestSystem.kt. They should mutate player/world state and publish events rather than directly own rendering or persistence.

Rendering, Assets, and Audio

Rendering is split between asset resolution, render orchestration, procedural visuals, and composited sprites:

• app/src/main/kotlin/com/wanderingquantum/graphics/AssetLoader.kt

• app/src/main/kotlin/com/wanderingquantum/graphics/RenderEngine.kt

• app/src/main/kotlin/com/wanderingquantum/graphics/LayeredSpriteRenderer.kt

Runtime art/audio is packaged under app/src/main/assets/sprites, app/src/main/assets/tilesets, and app/src/main/assets/audio. Audio playback/control is separated into app/src/main/kotlin/com/wanderingquantum/engine/AudioEngine.kt and app/src/main/kotlin/com/wanderingquantum/systems/MusicManager.kt.

UI Boundary

Gameplay presentation is handled by game UI components rather than a web frontend:

• app/src/main/kotlin/com/wanderingquantum/ui/HUDOverlay.kt

• app/src/main/kotlin/com/wanderingquantum/ui/ModalManager.kt

Android theme resources live separately under app/src/main/java/com/wanderingquantum/ui/theme. Input enters through app/src/main/kotlin/com/wanderingquantum/systems/InputManager.kt, is interpreted by player/gameplay controllers, then propagates to rendering/UI through current state and events.