RailSim Agent Guide

RailSim is a Devvit app that uses three.js to render a simple train simulation for Reddit. The actual project lives inside the

railsim/

directory.

Project Structure

railsim/src/main.js

– entry module exporting

initRailSim(container)

; returns

dispose()

for cleanup.

```
railsim/package.json
```
– NPM scripts and three.js dependency.
```
railsim/devvit.yaml
```
– minimal Devvit configuration.
```
RESEARCH.md
```
– background notes and useful references.

Development Workflow

```
cd railsim
```
```
npm install
```
```
npm test
```
(no tests yet; this will report "no test specified")
```
npm run dev
```
to launch a playtest session.
- You may need to authenticate with Devvit via
```
npx devvit login
```
  outside the container.

Current Functionality

Renders a dual-rail track with one or more train boxes.
Keyboard arrows move the first train and camera.
Mouse navigation via
```
OrbitControls
```
.
UI buttons allow pausing, adjusting train speed, and adding trains.
Cleanup routine removes listeners, DOM nodes, trains, and disposes three.js resources.

Ongoing Goals

Implement track switching and basic collision handling.
Expand the management UI for additional train controls.
Maintain thorough cleanup to avoid memory leaks in repeated mounts.

Plan Style Consideration

Three styles were evaluated:

Waterfall: clear phases but too rigid for exploratory feature work.
Kanban: flexible yet can drift without defined milestones.
Milestone-based iterative: groups related tasks into small releases, balancing structure and adaptability.

We will use the milestone-based approach so each iteration delivers a cohesive feature set and provides natural checkpoints for review.

LLM-Assisted Development Plan

Track Switching Infrastructure
- Model track segments and junctions.
- Allow trains to choose paths at switches via a simple UI.
Collision Detection
- Track each train's position along the rails.
- Halt and highlight trains that occupy the same segment simultaneously.
Enhanced Train Management UI
- List all trains with controls for speed, pause, and removal.
- Persist user changes during the session.
Modularization and Testing
- Extract track and train logic into separate modules.
- Add basic unit tests for pathing and collision checks.
Deployment Prep
- Document setup and usage in
```
README
```
  .
- Configure CI for linting and tests.

Plan Style Consideration

Three styles were evaluated:

Waterfall: clear phases but too rigid for exploratory feature work.

Kanban: flexible yet can drift without defined milestones.

Milestone-based iterative: groups related tasks into small releases, balancing structure and adaptability.

We will use the milestone-based approach so each iteration delivers a cohesive feature set and provides natural checkpoints for review.

LLM-Assisted Development Plan

Track Switching Infrastructure

Model track segments and junctions.
Allow trains to choose paths at switches via a simple UI.

Collision Detection

Track each train's position along the rails.
Halt and highlight trains that occupy the same segment simultaneously.

Enhanced Train Management UI

List all trains with controls for speed, pause, and removal.
Persist user changes during the session.

Modularization and Testing

Extract track and train logic into separate modules.
Add basic unit tests for pathing and collision checks.

Deployment Prep

Document setup and usage in
```
README
```
.
Configure CI for linting and tests.

RailSim Agent Guide

RailSim Agent Guide

Project Structure

Development Workflow

Current Functionality

Ongoing Goals

Plan Style Consideration

LLM-Assisted Development Plan

Related Skills

Markdown Converter

Nano Banana Pro

1password

RailSim Agent Guide

Project Structure

Development Workflow

Current Functionality

Ongoing Goals

Plan Style Consideration

LLM-Assisted Development Plan