# Train System Notes > Apply core train invariants for rail graph topology, front/back node semantics, rail position ordering, docking references, reverse behavior, deterministic distance handling, and TrainUnit snapshot boundaries. Use when implementing or debugging train movement/topology consistency and directional rail semantics. Use when this capability is needed. - Skill: `tomevault-io/train-system-notes` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/train-system-notes` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/train-system-notes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/train-system-notes --- # Train System Notes ## Overview Use this skill as a guardrail for train fundamentals and deterministic behavior. ## Reuse-First Rule - Before adding rail/train algorithm helpers, search existing implementations first. - Prefer canonical `Game.Train` logic over client-local duplication. - If duplication is unavoidable, record `WHY_NEW_IMPLEMENTATION` in code/PR notes. - Recommended pre-check: - `rg --line-number "RailPosition|OppositeNode|TrainUnit\.Reverse|Dock|Overlap" moorestech_client/Assets/Scripts moorestech_server/Assets/Scripts` ## Core Invariants - Treat `TrainUnit` as composition and synchronization boundary. - Reverse train direction with `TrainUnit.Reverse()`, not by mutating only `RailPosition`. - Keep deterministic distance handling (integer-based persisted distances). - Treat docking handles as source of truth for docking state. ## Train Sync Invariants - Structural TrainUnit/TrainCar changes should flow through per-unit snapshot notify path. - Deletion should clear both cache state and visual/car representation on apply. - Full snapshot API remains canonical recovery path on mismatch/resync. ## Rail Graph Model Invariants - Each rail component has directional endpoints (`FrontNode`/`BackNode`) as opposite pairs. - Front/back semantics are directional graph semantics, not cosmetic naming. - Avoid ad-hoc symmetric edge duplication that breaks opposite-node meaning. ## Rail Position Rules - Node ordering is semantic and must match traversal assumptions. - Validate adjacency in direction-aware way before constructing paths. - Add assertions/tests that catch invalid order early. - Verify forward and reverse reachability in deterministic scenarios. ## Station and Docking Notes - Keep station/cargo node pairing consistent with directional routing semantics. - Avoid duplicate manual station edge wiring in tests. - Restore docking links after train registration in save/load flow. ## TrainCar Direction and Traction - Backward-facing cars keep weight but do not produce traction. - Preserve orientation via `IsFacingForward` through save/load and snapshot paths. - If schema migration is needed, implement explicit migration logic. ## Workflow 1. Extract applicable invariants before editing. 2. Encode invariants as tests/assertions. 3. Implement change. 4. Re-run relevant deterministic train tests. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/moorestech) — claim your Tome and manage your conversions.