Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Self-play / ML hooks: a steppable match API

Open
  • Is something wrong?
#123 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Quiet
Tech stack
javascript, typescript
Domain
api, backend, game-dev, machine-learning

Research direction

Start in server/src/types/environment.ts and trace tick(), drainBotWork(), and the runLoop pause guard; then review the /restart, /pause, and /speed routes in server/src/api/arena.ts and step_arena peers in server/src/api/mcp.ts. The issue names test/simulationIntegration.test.ts, test/api.test.ts, and test/mcp.test.ts for coverage. Done means bounded manual stepping returns arena state while respecting ownership, rate limits, and the live-loop guard.

Written by the indexing model from the issue text.

Description

enhancement priority: medium

A headless, steppable match API (run-N-ticks, read state) so people can train bots with reinforcement learning. The hard prerequisites already exist — a deterministic simulation, seeded RNG, and unbounded "max" speed — so what remains is an explicit step/read-state control (today you approximate it with set_arena_speed "max" + arena_status).

Effort: L

Migrated from ENHANCEMENTS.md (§4 Developer experience).

Implementation notes

Priority: medium — High-value for a niche (RL/tooling) audience, purely additive host-side API with no impact on core UX or stability for the primary browser-game user base.

Purpose

Lets an external RL/training loop drive a match tick-by-tick and read exact state after each step, instead of polling an unbounded run_match/SSE stream on wall-clock timers — turning the existing deterministic sim into a real training environment (gym-style step()), which is pure upside for stability since it adds no new bot-facing surface.

Implementation approach
  • Add a public Environment.step(n) in server/src/types/environment.ts that calls the existing private tick() (used today only by runLoop) n times synchronously in a loop, awaiting drainBotWork() each time — reuse tick()/drainBotWork() as-is, don't fork the physics.
  • Guard against racing the self-scheduling runLoop: only allow step() when !this.looping (mirrors the resume() guard at environment.ts:537), erroring otherwise so REST/MCP callers must pause first, matching runMatchToDecision's pause/resume dance in server/src/api/mcp.ts.
  • Cap ticks per call (an Environment.MAX_DRAIN_ROUNDS-style constant) to bound compute per request.
  • REST: new POST /step route in server/src/api/arena.ts registered via the existing dual() helper (alongside /restart, /pause, /speed), gated requireOwner, under the compute rate limiter (middleware/rateLimit.ts). Response body: buildArenaStatus (util/arenaStatus.ts) so state is read in the same round-trip — no SSE needed for a training loop.
  • MCP: new step_arena tool in server/src/api/mcp.ts beside run_match/run_tournament, using the same ownedArena resolution and returning arena_status/match_summary-shaped output.
  • No compiler.ts / bot-facing API changes — this is host-side orchestration, not something bots call.
  • UI: no required change (headless callers bypass SSE), but note Environment.tick() still emits 'tick' events, so if a spectator has the arena open via ui/src/util/arenaReducer.ts while an external stepper drives it, ticks appear normally — nothing in simulate.ts needs to change since it only interpolates between server ticks.
Key details to plan
  • No DB/service changes: speed/seed/step are in-memory-only Environment fields already (see #142 re: no migrations).
  • Determinism relies on existing seeded PRNG (setSeed/util/random.ts) — step API should document that reproducibility needs seed+step count, not wall time.
  • Security: bound n and rate-limit like other compute-heavy MCP tools; reuse requireOwner/ownedArena ownership checks, no new sandbox exposure.
  • Testing: extend test/simulationIntegration.test.ts's manual-tick pattern (tick/setClock from test/simEnv.ts) for Environment.step; add REST cases to test/api.test.ts (ownership/rate-limit/400s) and MCP cases to test/mcp.test.ts alongside existing run_match tests.
  • Depends loosely on #142 (DB migrations) only if step state is ever persisted (it shouldn't be). Effort L is realistic — main risk is get the looping/pause interaction right so headless stepping can't double-run against a live runLoop.
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
11h 21m
Merged PRs (30d)
21

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from LeeAdcock/robocodeJs.com

All issues in LeeAdcock/robocodeJs.com

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.