mirror of
https://github.com/SlimeVR/SlimeVR-Server.git
synced 2026-11-21 01:21:25 -08:00
3.6 KiB
3.6 KiB
OpenCode Agent Instructions
Environment & Tooling
- Server (Kotlin/Java): Use
gradle(./gradlew).- Run:
./gradlew run - Build:
./gradlew shadowJar - Format:
./gradlew spotlessApply
- Run:
- GUI (Electron/TS): Use
pnpm.- Install:
pnpm i - Dev:
pnpm gui - Build:
pnpm package:build - Format:
pnpm run lint:fix
- Install:
- SolarXR Protocol (Submodule): Use
bashandpnpm.- Edit: Only
schema/files. - Generate:
./generate-flatbuffer.sh(Linux/macOS). - Sync: Run
pnpm iin root after generation.
- Edit: Only
Architecture: The Reducer/Behaviour Pattern
The server uses a reactive reducer pattern for thread safety and observability.
- Core Primitives:
Context<S, A>: HoldsStateFlow<S>,CoroutineScope, andBehaviours.Behaviour<S, A, C>:reduce(state, action): Pure function. No side effects.observe(receiver): Side effects. Launch coroutines usingreceiver.context.scope.
- Lifecycle:
Module.create()(inert construction)\rightarrowmodule.startObserving()(side-effect activation). - DI: Uses
Phase1ContextProvider\rightarrowAppContextProviderhierarchy. - Communication: Modules communicate via
dispatch(action)or by observing another module'sStateFlow.
Design & Coding Preferences
- Function over Class: Prefer plain functions or
objectover classes for single-purpose logic. - Function over Extension: Use plain functions instead of extension functions unless the receiver is the primary subject.
- Action Selection:
- Use
Update(with a lambda) for internal state changes that require no external reaction. - Use Named Actions when multiple behaviours must react to a specific event.
- Use
- State Management: Only include data in
StateFlowif it is required for observation by other modules. - Communication: Decouple modules by using
dispatchor observingStateFlowrather than direct method calls.
Agent Workflow
- Phase 1: Discovery: Use the
Glob\rightarrowGrep\rightarrowReadpattern. Never guess file paths or contents. - Phase 2: Planning: For complex tasks, use
todowriteto create a checklist. Present the plan to the user before implementation. - Phase 3: Implementation: Use
editfor existing files;writefor new files. - Phase 4: Verification: Always run the relevant linting or testing tools before marking a task as complete.
Common Pitfalls
- Coroutine Leaks: Never launch coroutines in
observeusing a global scope; always usereceiver.context.scope. - Direct State Mutation: Never attempt to mutate state properties directly. Always use
dispatch(action). - Incomplete Cleanup: Ensure any module owning a
Contextimplements adispose()method.
Conventions
- Files:
module.kt(Class/State/Actions) andbehaviours.kt(Implementations). - Actions: Use
sealed interface. - State: Data classes must use
valonly. - Cleanup: We use a direct
dispose()method on modules instead of aDisposableinterface. - Detailed Conventions: See
server/README.mdfor full coding style and architecture details.
Testing
- Reducers: Test by creating a
Contextwith specificBehaviours. - Modules: Use
TestAppContextandbuildTest...helpers fromTestServer.kt.
Verification Protocol
- Linting: Run
./gradlew spotlessApply(Server) orpnpm run lint:fix(GUI). - Testing: Identify and run the relevant test suite (e.g.,
./gradlew testor specific module tests). - Final Audit: Perform a final
git diffcheck to ensure no unintended changes were made.