StasisWarden-Legacy/docs/stories/1.3.story.md

Story 1.3: The Lonely Power Core

Status

• Approved

Story

As the AI, I want to start the game with a view of a single, powered room—the Power Core— so that I have a clear starting point for my actions.

Acceptance Criteria

1. When the game starts, a top-down view of one room, the "Power Core," is displayed on the CRT monitor.
2. The Power Core room has a distinct visual representation on the ship map.
3. The player can hover over and click on the Power Core object within the room.

Tasks / Subtasks

• Task 1: Set Initial Game View to Power Core Room (AC: 1)
  • Configure the main game scene to load and display the Power Core room at startup.
  • Ensure the room is framed correctly within the CRT monitor UI.
• Task 2: Create Power Core Room Scene (AC: 2)
  • Design and create a scene for the Power Core room (/scenes/levels/PowerCoreRoom.tscn).
  • Add a distinct visual element (sprite or mesh) to represent the Power Core within the room scene.
  • Assign a unique identifier or tag to the Power Core object for interaction.
• Task 3: Implement Power Core Interaction (AC: 3)
  • Add an Area2D node to the Power Core object to detect mouse hover and click events.
  • Implement signal connections for mouse_entered and mouse_exited to provide hover feedback (e.g., highlight).
  • Implement signal connection for input_event to handle click interactions.
• Task 4: Unit Testing for Room and Interaction (AC: 1, 2, 3)
  • Write a test to verify that the game starts by loading the PowerCoreRoom.tscn scene.
  • Write a test to confirm the presence and correct configuration of the Power Core object within the room scene.
  • Write a test to simulate a mouse click on the Power Core and verify that the interaction logic is triggered.

Dev Notes

Technology Stack

• Game Engine: Godot (Version 4.x recommended) [Source: docs/sharded-architecture/7-technology-stack.md]
• Programming Language: GDScript [Source: docs/sharded-architecture/7-technology-stack.md]
• IDE: Visual Studio Code [Source: docs/sharded-architecture/7-technology-stack.md]
• Version Control: Git [Source: docs/sharded-architecture/7-technology-stack.md]

Project Structure Notes

• Source: docs/sharded-architecture/unified-project-structure.md
• The main game level/room scene should be located at /scenes/levels/.
• Specific room scenes like PowerCoreRoom.tscn should be placed in /scenes/levels/.
• Scripts for level logic should be in /scripts/entities/ or potentially /scripts/core/ if they are manager-level.
• Interaction logic for objects like the Power Core should be in a script attached to the object or its parent, likely in /scripts/entities/.

Coding Standards

• Source: docs/sharded-architecture/coding-standards.md
• All GDScript code must adhere to the defined standards. This includes PascalCase for classes/nodes, snake_case for functions/variables, mandatory type hinting, and the use of class_name for all scripts.
• Scene and node names should be in PascalCase.
• Use @onready for node references.
• Use static type hints for variables, function arguments, and return values.

Testing

• Source: docs/testing-strategy.md
• Unit tests for scenes and game logic should be created using the selected framework (GUT).
• Tests should verify scene instantiation, the presence of key child nodes, and the correct functioning of game logic.
• Test files should be placed in the /tests/ directory.
• For this story, focus on testing the initial scene load and Power Core interaction logic.

Previous Story Insights (1.2)

• The project structure is set up with /scenes/ui/ and /scripts/ui/ directories. The new level scenes will go into /scenes/levels/.
• A unit testing framework (GUT) is in use. Tests for UI scenes were created in /tests/.
• The MainHUD.tscn is the main UI scene. The main game content will likely be displayed in a separate scene/container that is managed by the main scene or a game manager.
• The CRT monitor effect is applied via a shader. The main game view needs to be correctly positioned/framed within this effect.

Frontend Architecture Guidance

• Ship Map (ShipMap.tscn): Likely a TileMap for the grid-based layout of the ship. Each room will be its own scene instance placed on the map. [Source: docs/sharded-architecture/4-scene-node-architecture-frontend.md]
• Rooms: Rooms will have Area2D nodes to detect clicks for interaction. [Source: docs/sharded-architecture/4-scene-node-architecture-frontend.md]
• For this story, we are implementing the initial PowerCoreRoom.tscn and placing the Power Core object within it.

File Locations (Based on Project Structure)

• Power Core Room Scene: /scenes/levels/PowerCoreRoom.tscn
• Power Core Room Script: /scripts/entities/PowerCoreRoom.gd (if needed for room-specific logic)
• Power Core Object Script: /scripts/entities/PowerCoreObject.gd (attached to the Power Core node)
• Main Game Scene/Manager: Likely /scenes/levels/MainGame.tscn or similar, managed by a script in /scripts/core/.
• Test Files: /tests/test_power_core_room.gd

Data Models

• No specific data models are required for this story beyond the basic scene structure and node setup.
• Future stories will introduce data for resources and crew, managed by ResourceManager and CrewManager. [Source: docs/sharded-architecture/5-scripting-game-logic-architecture-backend.md]

API Specifications

• No API endpoints are involved in this story as it's a local, client-side implementation.
• Interaction will be handled through Godot's signal system and internal game logic.

Component Specifications

• PowerCoreRoom.tscn: The scene representing the initial game area. [Source: Story Requirements]
• Power Core Object: A node within PowerCoreRoom.tscn that the player can interact with. [Source: Story Requirements]
• Area2D: Godot node used for detecting mouse interactions on the Power Core object. [Source: Godot Documentation & Story Requirements]

Technical Constraints

• The initial view must be correctly framed within the existing CRT monitor UI from Story 1.2.
• Interactions should be responsive and provide clear feedback.

Testing

• Framework: Use the GUT framework for unit testing. [Source: Dev Notes > Testing]
• File Location: Place test files in the /tests/ directory. [Source: Dev Notes > Testing]
• Standards: Tests should verify scene instantiation, the presence of key child nodes, and the correct functioning of game logic. [Source: Dev Notes > Testing]
• Requirements for this Story:
  • Write a test to verify that the game starts by loading the PowerCoreRoom.tscn scene. [Source: Task 4.1]
  • Write a test to confirm the presence and correct configuration of the Power Core object within the room scene. [Source: Task 4.2]
  • Write a test to simulate a mouse click on the Power Core and verify that the interaction logic is triggered. [Source: Task 4.3]

Change Log

Date	Version	Description	Author
2025-08-24	1.0	Initial draft based on Epic 1 requirements and architecture documents.	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results