Alone-in-the-Dungeon

Imported from MuziRain-official/Alone-in-the-Dungeon (AGENTS.md). Install upstream with npx skills add MuziRain-official/Alone-in-the-Dungeon. Copyright stays with the author.

Alone in the Dungeon - Agent Guide

Scope

This file applies to the whole repository. The actual Unity project root is Alone in the Dungeon/, one level below the Git repository root. Run Unity, package, and project-setting operations from that nested directory.

This is a solo-developed Unity 2D top-down dungeon shooter demo. Preserve the existing gameplay and serialized scene/prefab contracts unless a task explicitly asks for a redesign.

Project Snapshot

• Unity: 6000.2.10f1.
• Rendering: Universal Render Pipeline 2D (com.unity.render-pipelines.universal).
• Input: Unity Input System (com.unity.inputsystem).
• Camera: Cinemachine 3 with a CinemachineConfiner2D per active room.
• UI: uGUI.
• Main custom code: Alone in the Dungeon/Assets/Script/.
• Build scenes, in order: Assets/Scenes/TitleScene.unity, then Assets/Scenes/SampleScene.unity.
• Custom scripts compile into the default Assembly-CSharp; there are currently no custom asmdef files and no project-authored automated tests.

Repository Map

• Alone in the Dungeon/Assets/Scenes/: the title and gameplay scenes.
• Alone in the Dungeon/Assets/Prefab/: gameplay composition for the player, enemies, rooms, objects, UI, weapons, and projectiles.
• Alone in the Dungeon/Assets/Script/GameFramework/: typed event bus, service locator, gameplay interfaces, and two-phase module initialization.
• Alone in the Dungeon/Assets/Script/PlayerController/: input adapters, movement, aim/orientation, dash, health, animation, interaction, and the active pickup/equip weapon controller.
• Alone in the Dungeon/Assets/Script/EnemyController/: shared enemy health, movement, animation wiring, melee/ranged attacks, retreat behavior, and the Boss state machine.
• Alone in the Dungeon/Assets/Script/Room/: room combat gates, room events, and camera-bound switching.
• Alone in the Dungeon/Assets/Script/Object/: doors, signs, traps, breakables, and health phials.
• Alone in the Dungeon/Assets/Script/UIController/: title, HUD, pause, game-over, and Boss-health UI.
• Alone in the Dungeon/Assets/Script/Audio/: persistent music and SFX service.
• Alone in the Dungeon/Assets/Animation/, Resources/, TilePalette/, and Settings/: authored content and render configuration.
• Alone in the Dungeon/Assets/TextMesh Pro/Examples & Extras/: imported sample content, not project gameplay code.
• Alone in the Dungeon/Library/, Temp/, Logs/, and obj/: generated Unity data; do not edit or document as source.
• Alone in the Dungeon/本体/ and 本体.zip: generated Windows build artifacts, not the editable game implementation.
• temp_backup/: historical backup material, not an active runtime source.

Runtime Architecture

Scene Bootstrapping

TitleScene contains MenuUI, which loads the configured gameplay scene. SampleScene is the composition root and contains or instantiates:

• a GameFramework object with EventManager and ServiceLocator;
• the Player prefab;
• the UIManager prefab;
• AudioManager and its music/SFX sources;
• normal Room prefab instances and a BossRoom instance;
• the main camera, Cinemachine camera, and 2D lighting.

EventManager has execution order -100. LifecycleManager has order -90 and is created automatically when the first IGameModule registers during Awake. At Start, it first calls RegisterEvents() on every module and then calls SubscribeEvents(). Modules currently include PlayerHealth, EnemyHealth, Room, BossLogic, and UIManager.

Do not remove the scene-level EventManager or ServiceLocator: most systems have compatibility fallbacks, but the intended architecture depends on these services being available before gameplay begins.

Communication Layers

The codebase intentionally uses several communication mechanisms:

1. IDamageable and IHealable decouple projectiles, traps, enemies, players, and healing pickups from concrete health components.
2. IEnemyAttacker gives EnemyMovement and EnemyManager a common view of melee and ranged attack state/events.
3. EventManager publishes typed struct events across feature boundaries: player damage/heal/death, enemy death, Boss activation/damage, room entry and clearing, and game pause.
4. ServiceLocator exposes IPlayerProvider, IAudioService, and IUIService.
5. Local C# events connect components on the same actor, such as enemy health and movement to animation, or enemy death to its owning room.

Prefer interfaces for direct gameplay interactions, local events within one actor/aggregate, and EventManager for cross-system notifications. Subscribe and unsubscribe symmetrically. New typed global events must be registered by the module that owns them before they are published.

Gameplay Modules

Main Gameplay Flows

Player Input

Assets/Script/PlayerController/InputSystem_Actions.inputactions defines the Player and UI action maps. The Player prefab uses PlayerInput with Unity Event notification behavior. Important callbacks are serialized in the prefab and overridden in SampleScene, including:

• move -> InputHandler.OnMove -> MovementController.FixedUpdate;
• sprint/accelerate -> InputHandler.OnSprint;
• attack -> WeaponController.OnAttack -> equipped WeaponFire;
• interact -> PlayerInteract.TryInteract and weapon interaction;
• skill -> DashSkill.Dash;
• pause -> UIManager.TogglePauseMenu through a scene override.

When changing input, inspect all three of the action asset, Player.prefab, and the SampleScene prefab overrides. A C# rename alone can silently break an Inspector event binding.

Combat and Health

Player and enemy projectiles resolve IDamageable on collision. Traps use the same interface, and health phials resolve IHealable. PlayerHealth and EnemyHealth own health values, invoke local events, play SFX, and publish typed events. UIManager consumes the global player and Boss events.

DashSkill temporarily makes the player's collider a trigger, grants invulnerability, damages each crossed enemy once, and applies a short local hit stop. Changes to dash physics must be tested against walls, enemies, pickup triggers, and restoration of the collider/weapon after the dash.

Rooms and Boss

Room searches its Enemys child at Start, subscribes to each EnemyHealth.OnDied, closes configured door objects when the player enters a non-empty room, and opens them after the last enemy dies. It publishes PlayerEnterRoomEvent and RoomClearedEvent.

BossLogic activates only when a room-entry event names an ancestor room of the Boss. Its state machine moves among idle selection, fixed-point movement, shooting, and second-phase player chasing. Boss damage drives animation, health UI, and music phase changes. Boss death stops combat, plays victory music, and activates TowerController; interacting with the tower returns to the title scene.

Scene and Prefab Contracts

Treat scenes, prefabs, .meta GUIDs, tags, layers, animator parameters, child names, and Inspector references as part of the code contract.

• Player.prefab carries all active player components and both weapon prefab references. Expected child lookup names include WeaponPoint and Weapon.
• Slime.prefab uses melee EnemyAttack; Soldier.prefab uses EnemyShoot, EnemyFire, and EnemyRetreat.
• Boss 1.prefab uses BossLogic plus shared EnemyHealth and references its projectile prefab.
• Room.prefab contains ordinary enemies, doors, props, hazards, and a RoomCameraBoundSetter; BossRoom.prefab contains the Boss composition.
• Room expects its enemy container to be named exactly Enemys.
• RoomCameraBoundSetter expects a sibling/parent child named Virtual when its collider is not assigned directly.
• Gameplay tags include Player, Enemy, PlayerBullet, Obstacle, Object, Background, and trap; tag spelling and capitalization are significant.
• Animator code expects player parameters isMoving, isHurt, and isDash; shared enemies use isMoving, Attack, and Hurt; the Boss uses isMove, isHurt, and isDie.
• Preserve every asset's .meta file. Move or rename Unity assets through the Unity Editor whenever possible so GUID-backed references remain valid.

Migration and Legacy Status

The architecture is midway through a refactor from direct singleton/component access to interfaces, a service locator, and typed events. Do not accidentally expand both paths.

• PlayerHealth and EnemyHealth expose local/legacy events while also publishing EventManager events.
• Several systems prefer ServiceLocator but fall back to PlayerManager.Instance or AudioManager.instance.
• The active serialized weapon implementation is PlayerController/WeaponController. WeaponSystem/WeaponManager.cs is an unreferenced object-pool/switching experiment and should not be treated as active without explicitly wiring it.
• CameraLogic, generic MyInstance<T>/GameManager, and EnemyEffect outside death-effect prefabs are small legacy/utility pieces; confirm serialized usage before building on them.
• Prefer completing the established interface/event path in touched code, but do not perform a broad migration as part of an unrelated feature or bug fix.

Working Rules

• Keep changes scoped to the feature's scripts and their owning prefab/scene.
• Read the relevant prefab and scene overrides before changing a serialized field, callback name, hierarchy lookup, tag, layer, or animator parameter.
• Do not hand-edit large Unity YAML files for routine object changes; use the Unity Editor. If text editing is unavoidable, make a minimal diff and validate the scene/prefab in Unity afterward.
• Do not modify imported TextMesh Pro examples, generated directories, build output, or backup copies to implement gameplay behavior.
• Avoid adding another singleton or global lookup when an existing interface, local actor reference, or typed event already represents the dependency.
• Avoid Find* calls in update loops. Existing retry/fallback lookups are migration compatibility, not a preferred pattern for new code.
• Use physics work in FixedUpdate, input/state timers in Update, and Inspector fields for designer-tuned gameplay values, following the existing codebase.
• Keep OnDestroy/OnDisable cleanup paired with every event or Input System subscription.
• Local work tracking, when needed, lives as Markdown under .scratch/<feature>/.
• Preserve unrelated working-tree changes. In particular, do not overwrite scene or animation edits merely to normalize serialized files.

Validation

For any gameplay change:

1. Open Alone in the Dungeon/ with Unity 6000.2.10f1 and allow scripts to compile with no Console errors.
2. Run from TitleScene, start the game, and verify the changed flow in SampleScene; direct gameplay-scene testing does not cover title-to-game persistent services.
3. Exercise the owning prefab in context: player input/combat, normal room clear, Boss activation/phase/death, pause/resume, restart, and return to menu as relevant.
4. Inspect the final Git diff for unintended scene/prefab churn and missing or replaced .meta files.
5. If logic is separated enough to test, add Unity Test Framework EditMode or PlayMode tests. The repository currently has no custom test suite, so report manual verification explicitly.

Known Risks

• The README records a known dash wall-clipping bug and intermittent player/Boss health-bar display errors.
• Initialization depends on scene composition plus Unity Awake/Start order; test scene reload, restart, and return-to-menu paths when changing persistent services or event registration.
• Serialized input callbacks contain historical overrides and are easy to break through class/method renames.
• The two weapon implementations can be confused because both use the PlayerController namespace; serialized references, not filenames alone, determine the active path.
• There is no automated regression coverage or assembly boundary around gameplay code, so shared framework changes have a broad blast radius.