{
  "markdown": "# Unity ECS / DOTS Knowledge Base (OpenKnowledge + OKF)\n\nAn authoritative, curated [OpenKnowledge](https://openknowledge.ai/) knowledge base delivering high-performance **Unity Entities 1.4+ (DOTS)** patterns to AI developer assistants via the **Model Context Protocol (MCP)**.\n\nThis repository serves as the dedicated backend for an OpenKnowledge server running the Open Knowledge Format (`okf`) plugin. It isolates the knowledge base and OpenKnowledge Git hooks into an independent repository, ensuring clean separation from target game codebases and development harnesses.\n\n---\n\n## Purpose & Problem Solved\n\nModern AI coding agents frequently hallucinate when writing Unity DOTS code due to mixed training data containing deprecated paradigms (e.g., obsolete `IAspect`, pre-1.0 hybrid patterns, or illegal managed allocations inside Burst jobs). \n\nThis repository provides an authoritative, zero-hallucination ground truth:\n* **Entities 1.4+ Canonical Standards**: Modern unmanaged `ISystem`, `[BurstCompile]`, `EntityCommandBuffer`, and Authoring/Baking workflows.\n* **Positive-Only Examples**: Strict adherence to working patterns with explicit \"Prefer X / Avoid Y\" guidance.\n* **Decoupled Architecture**: Running as an independent background MCP server allows multiple IDEs (ZooCode, VS Code, Antigravity, Rider) to query shared ECS knowledge concurrently over standard HTTP/SSE.\n\n---\n\n## Initialization & Seeding\n\nThis repository was initialized using the [OpenKnowledge CLI](https://openknowledge.ai/):\n\n```bash\n# 1. Initialize OpenKnowledge repository with custom content directory and JSON formatting\nok init --no-mcp --content-dir okf-ecs --no-skills --json\n\n# 2. Seed the OKF plugin for Open Knowledge Format schema management\nok seed -p okf --root .\\okf-ecs\n```\n\n### Directory Structure\n```\nunity.ecs.okf.repo/\n├── start_ok.ps1            # Windows PowerShell server launcher\n├── start_ok.sh             # macOS / Linux Bash server launcher\n├── README.md               # Repository documentation\n├── .ok/                    # OpenKnowledge project configuration and indexes\n└── okf-ecs/                # Designated content directory\n    ├── index.md            # Catalog root index\n    └── concepts/           # 23 canonical Entities 1.4+ concept cards (Layers 1–7)\n```\n\n---\n\n## Starting the Server\n\nThe server runs on port **`61894`** and exposes HTTP/SSE endpoints. Launch scripts are provided for Windows and Unix environments:\n\n### Windows (PowerShell)\nRun `start_ok.ps1`:\n```powershell\n$env:OK_RECLAIM_DISABLE = \"1\"\nok start -p 61894 --only server --idle-shutdown off\n```\n\n### macOS / Linux (Bash)\nRun `start_ok.sh`:\n```bash\n#!/bin/bash\nexport OK_RECLAIM_DISABLE=\"1\"\nexport OK_ALLOW_EXTERNAL=\"1\"\nok start -p 61894 --only server --idle-shutdown off\n```\n\n### Important Configuration Notes\n* **`OK_RECLAIM_DISABLE=1`**: **Crucial setting.** Prevents OpenKnowledge from running its auto-repair sweep against client configuration files (`mcp_config.json`). This ensures client MCP configurations referencing the HTTP/SSE URL remain intact and are not overwritten by local stdio process definitions.\n* **`--only server`**: Runs the standalone MCP server without launching the interactive terminal UI.\n* **`--idle-shutdown off`**: Keeps the server running indefinitely in the background so it remains responsive across agent sessions.\n\n### Endpoints\n* **MCP Protocol Endpoint (SSE)**: `http://127.0.0.1:61894/mcp`\n* **Readiness Probe**: `http://127.0.0.1:61894/readyz` (returns HTTP 200 when ready)\n* **Health Probe**: `http://127.0.0.1:61894/healthz` (returns HTTP 200 when healthy)\n\n---\n\n## Client MCP Configuration Examples\n\nConnecting to the OpenKnowledge server over HTTP/SSE eliminates local process spawning conflicts, reduces memory overhead, and allows multiple coding agents to share the same knowledge instance.\n\nAdd the following configuration snippet to your assistant's MCP configuration:\n\n### ZooCode / Roo Code (`.roo/mcp.json`)\n```json\n{\n  \"mcpServers\": {\n    \"open-knowledge\": {\n      \"serverURL\": \"http://127.0.0.1:61894/mcp\",\n      \"type\": \"sse\"\n    }\n  }\n}\n```\n\n### VS Code (`.vscode/mcp.json`)\n```json\n{\n  \"servers\": {\n    \"open-knowledge\": {\n      \"serverURL\": \"http://127.0.0.1:61894/mcp\",\n      \"type\": \"sse\"\n    }\n  }\n}\n```\n\n### Antigravity / Gemini CLI (`~/.gemini/config/mcp_config.json`)\n```json\n{\n  \"mcpServers\": {\n    \"open-knowledge\": {\n      \"serverURL\": \"http://127.0.0.1:61894/mcp\",\n      \"type\": \"sse\"\n    }\n  }\n}\n```\n\n---\n\n## Exposed MCP Tools\n\nWhen connected, the server exposes the standard OpenKnowledge tool suite:\n\n* **`open-knowledge:search`**: Keyword and semantic search across the entire concept card library.\n* **`open-knowledge:read`**: Retrieves full card contents by slug (e.g., `concepts/baking` or `concepts/unity-input-system`).\n* **`open-knowledge:list`**: Lists all available cards and navigation structure.\n* **`open-knowledge:exec`**: Executes OpenKnowledge CLI management commands.\n\n---\n\n## Concept Curriculum (Layers 1–7)\n\nThe `okf-ecs/concepts/` directory contains 23 grounded concept cards:\n\n| Layer | Focus Area | Cards Included |\n| :--- | :--- | :--- |\n| **Layer 1** | **Core Paradigms** | `ecs-fundamentals.md`, `ecs-components.md` |\n| **Layer 2** | **Data Layouts & Types** | `singletons.md`, `enableable-components.md`, `dynamic-buffers.md`, `cleanup-components.md`, `aspects.md` |\n| **Layer 3** | **Execution & Scheduling** | `ecs-systems.md`, `entity-queries.md`, `jobs-native-collections.md`, `random-in-ecs.md` |\n| **Layer 4** | **Structural Changes & Lifecycle** | `ecb-structural.md`, `ecb-best-practices.md`, `entity-spawning.md` |\n| **Layer 5** | **Authoring & Scene Assembly** | `baking.md`, `ecs-scene-architecture.md`, `agentic-scene-assembly.md` |\n| **Layer 6** | **Cross-Paradigm Bridges** | `hybrid-ecs.md`, `unity-input-system.md`, `unity-ui-performance.md`, `unity-asset-streaming.md` |\n| **Layer 7** | **Diagnostics & Optimization** | `common-compilation-errors.md`, `unity-platform-optimization.md` |\n\n---\n\n## References\n\n* **OpenKnowledge**: [https://openknowledge.ai/](https://openknowledge.ai/)\n* **Unity Entities Documentation**: [Unity Entities Package Manual](https://docs.unity3d.com/Packages/com.unity.entities@1.4/manual/index.html)\n* **AI Development Harness**: Used alongside [unity.ai.dev.harness](https://github.com/dennis/unity.ai.dev.harness)\n",
  "bytes": 6353,
  "sha": "75f4c3fec4f7d49a5da6e4abbf3bdab3d6fb0d9ac2ae2ce6147ec3993ae8a22a",
  "repo_slug": "dennisfederico/unity.ecs.okf.repo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_dennisfederico_unity_ecs_okf_repo_okf_ec_9fab1230/readme"
}