Skip to content

dev-workflow.md

Latest commit

 

History

History
181 lines (127 loc) · 6.13 KB

dev-workflow.md

File metadata and controls

181 lines (127 loc) · 6.13 KB

Developer Workflow Guide

Goal

W0 exists to keep the repository deterministic and reviewable before kernel work scales. Every local setup should run the same commands, use the same tool versions, and hit the same guardrails.

Required Tools

First-Time Setup

mise install
mise run install
mise run sourcemap
mise run test

Daily Command Loop

mise run format
mise run lint
mise run test     # Full regression suite W2-W8 (see docs/test-strategy-v2.md)
mise run serve

Run mise run sourcemap again whenever the Rojo tree changes.

Luau LSP and Rojo (Cursor / VS Code)

The extension cannot find the rojo binary if it is only installed via mise (not on PATH for the GUI app).

  1. Workspace settings (.vscode/settings.json) set luau-lsp.sourcemap.autogenerate to false so the LSP does not spawn Rojo itself.
  2. Generate the map with the same toolchain as the repo: mise run sourcemap (writes sourcemap.json; gitignored).
  3. Reload the window (Developer: Reload Window) or restart the Luau language server.

default.project.json mounts src/shared under both ReplicatedStorage.Shared and StarterPlayer.StarterPlayerScripts.Shared so client require(script.Parent.Parent.Parent.Shared...) matches the DataModel. Require-able gameplay modules should stay on plain .luau; reserve .server.luau / .client.luau for actual bootstrap scripts so Rojo and Luau LSP agree on instance class.

Test Tiers

Tier When to Run Coverage
smoke Every commit Repo structure, tooling, naming
unit Every PR Pure rules + service adapters
simulation PR-029+ Full chain: matchmaking → dungeon → boss
release-candidate PR-031+ Full regression + staging playtest

See docs/test-strategy-v2.md for full coverage map.

Editor Setup

The repo ships with:

  • .vscode/settings.json for Luau formatting on save
  • .vscode/extensions.json for the minimum recommended extensions

In Studio, enable the Luau LSP Companion plugin before relying on intellisense.

Git Posture

  • Keep changes patch-sized.
  • One subsystem per branch or PR.
  • Do not mix repo OS work with gameplay design changes.
  • Record validation and rollback notes in the PR description.

Use the task and PR templates in:

File Naming Rules

Type Pattern Example
Server bootstrap Something.server.luau Bootstrap.server.luau
Server module/service Something.luau CombatService.luau
Client bootstrap Something.client.luau ClientBootstrap.client.luau
Client module/controller Something.luau MovementController.luau
Shared config SomethingConfig.luau CombatConfig.luau
Shared types SomethingTypes.luau MovementTypes.luau
Tests *.spec.luau or repo smoke scripts in tests/ Parry.spec.luau

Sourcemap Notes

Rojo maps filesystem modules into the DataModel. sourcemap.json exists only to help tooling and should stay generated, not hand-edited.

Examples:

src/shared/Types/init.luau -> ReplicatedStorage.Shared.Types.init
src/server/Services/CombatService.luau -> ServerScriptService.Server.Services.CombatService

Troubleshooting

Intellisense looks wrong

  1. Run mise run sourcemap.
  2. Reload the editor window.
  3. Confirm Luau LSP Companion is enabled in Studio.

Rojo is not syncing

  1. Run mise run serve.
  2. Confirm default.project.json still matches the folder tree.
  3. Reconnect Studio to Rojo.

Studio Harness

The repo now ships with a Studio-only harness:

Default behavior:

  • no-op outside Studio
  • no-op in Studio unless GameConfig.debug.devHarness.autoRunInStudio = true

Manual run from the Server command bar while playing in Studio:

local results = require(game.ServerScriptService.Server.DevHarness).runAll()
print(results)

This harness can spawn two anchored dummy rigs in Workspace.HCLW_DevHarness, run a combat smoke, a dungeon smoke, and a boss smoke, then print/TestService-log a summary.

Assetless Playtest

Studio now has an assetless placeholder pipeline so combat can be played before real art/animation imports:

What it provides:

  • graybox combat room
  • graybox boss room
  • placeholder sword template (ReplicatedStorage.SwordOfLight)
  • targetable dummy enemies
  • free-spawn dummy types: neutral, attack, auto_parry, auto_block, auto_dodge, mixed
  • procedural slash / parry / dodge feedback
  • combat debug HUD with posture / tag / outcome / target state
  • nearest-target auto-lock for attack inputs

In Studio play mode:

  • press F8 to toggle the Studio dev panel
  • press F7 to toggle the combat debug HUD
  • press G to toggle the movement debug panel

Server command bar alternatives:

require(game.ServerScriptService.Server.PlaytestSceneService).spawnTestScene()
require(game.ServerScriptService.Server.PlaytestSceneService).spawnCombatScene()
require(game.ServerScriptService.Server.PlaytestSceneService).spawnBossScene()
require(game.ServerScriptService.Server.PlaytestSceneService).spawnDummy("auto_parry", 1)
require(game.ServerScriptService.Server.PlaytestSceneService).runHarness()

Repo checks fail

  1. Run mise run format.
  2. Run mise run lint.
  3. Run mise run test.
  4. Fix repo OS issues before touching gameplay logic.