DisasterSword

❗ AI Assistant Directives ❗

Primary Directive: As this project evolves, you must keep this README.md file up to date. Specifically, any changes to the control scheme, core game mechanics, or file structure must be documented in the relevant sections below. This ensures that the project's description remains accurate for both human developers and for your own context in future development sessions.

Pull Request Mandate: Prefix all pull request descriptions with the string [#disastersword].

Quick Start

The simulation is a Next.js application. To run it locally, navigate to the simulation/ directory and use the following commands:

1. Install dependencies:

   npm install

2. Run the development server:

   npm run dev

The application will be available at http://localhost:3000.

About This Project

DisasterSword is an experimental, hybrid simulation and game. It is being developed as a procedurally generated, roguelike platformer.

The core concept is a persistent world where an autonomous character explores and "lives" on its own. The simulation runs independently, but a player can choose to intervene and take direct control of the character at any time, turning the simulation into a playable game.

Current Features & Controls

• Platforming Environment: The game is built using the Phaser 3 engine and features a dynamic, procedurally generated platforming environment.
• Autonomous AI Character: A character navigates the world on its own. Its AI is currently simple: every two seconds, it randomly decides to move left, right, or stand still, with a chance of sprinting or jumping.
• Manual Player Control: A player can take direct control of the character using a "Possess" button in the UI.
  • Move: A / D or Left Arrow / Right Arrow
  • Jump: W, Up Arrow, or Spacebar (supports double jump)
  • Sprint: Hold Shift while moving.
  • Wall Jump: Press the jump key while sliding down a wall.
• Control Toggle: Switch between AI and manual control mode using the "Possess"/"Release" button in the top-right corner of the screen.

Procedural World Generation

The world is infinite and generated in chunks as the player explores. The core components of the generation system are:

• Chunk-Based Loading: The world is divided into 64x64 tile chunks. The game dynamically loads a 3x3 grid of chunks around the player, unloading chunks that are out of range. This allows for a theoretically infinite world without consuming excessive resources.
• Structure Placement: Each chunk is generated by placing a variety of pre-defined structures (platforms, walls, stairs, etc.) onto a grid. These structures are defined in simulation/src/game/generation/structures.js.
• Greedy Meshing: After structures are placed on the logical grid, a "greedy meshing" algorithm runs. This algorithm combines adjacent solid tiles into larger polygons. These polygons are then rendered as single, efficient physics bodies, which significantly improves performance compared to rendering each tile individually.

Code Structure

The project uses Next.js as its frontend framework and Phaser 3 as the core game engine.

• simulation/src/app/page.js: The main entry point for the Next.js application. It loads the GameLoader component.
• simulation/src/components/: Contains React components that bridge Next.js and Phaser.
  • GameLoader.js: Dynamically loads the PhaserGame component on the client side only (ssr: false).
  • PhaserGame.js: Initializes and manages the Phaser game instance and the UI overlay (e.g., the "Possess" button).
• simulation/src/game/: The core directory for all Phaser logic.
  • phaserConfig.js: Contains the main Phaser configuration object (dimensions, physics, etc.).
  • GameScene.js: The primary scene file where the main game loop, AI, player input, and chunk management are handled.
  • LevelGenerator.js: Responsible for orchestrating the procedural generation of the world.
  • generation/: Contains the building blocks for the level generation.
    • Grid.js: A simple 2D grid data structure.
    • Structure.js: A class that defines a piece of level geometry.
    • structures.js: A collection of pre-defined structures.
    • MegaStructure.js: A utility for creating large, repeating structures like the floor.
    • GreedyMesher.js: Implements the greedy meshing algorithm.
    • PlayerCapabilitiesProfile.js: Defines the physical abilities of the player, which can be used to tailor level generation.