pi-unity-docs

Pi package for fast, token-efficient retrieval from local Unity offline documentation.

The package builds a local SQLite FTS5 database from an installed Unity documentation folder such as:

C:\Program Files\Unity\Hub\Editor\6000.4.7f1\Editor\Data\Documentation\en

It does not copy raw HTML and does not generate Markdown/JSONL. The Unity install remains the source of truth; the generated database is a rebuildable cache.

The package can also build separate package/plugin documentation docsets from Unity package Documentation~ folders. Package docsets are managed separately from the core Unity docs cache and can be searched alongside it.

Install in pi

From npm:

pi install npm:@aefree/pi-unity-docs

Or try it for one session:

pi -e npm:@aefree/pi-unity-docs

For local development, replace the npm spec with the path to this checkout.

Configure and build

Interactive configuration from pi:

/unity-docs-configure

The command asks for:

• Unity documentation source directory
• database install directory
• Unity version label
• whether to build immediately

Windows non-interactive CLI (Git Bash)

For PowerShell, use $env:LOCALAPPDATA instead of $LOCALAPPDATA.

python scripts/unity_docs_db.py configure \
  --source "C:/Program Files/Unity/Hub/Editor/6000.4.7f1/Editor/Data/Documentation/en" \
  --db-dir "$LOCALAPPDATA/pi/unity-docs/6000.4.7f1" \
  --version 6000.4.7f1 \
  --yes

python scripts/unity_docs_db.py build \
  --source "C:/Program Files/Unity/Hub/Editor/6000.4.7f1/Editor/Data/Documentation/en" \
  --db-dir "$LOCALAPPDATA/pi/unity-docs/6000.4.7f1" \
  --version 6000.4.7f1 \
  --force \
  --progress

macOS non-interactive CLI

python3 scripts/unity_docs_db.py configure \
  --source "/Applications/Unity/Hub/Editor/6000.4.7f1/Unity.app/Contents/Documentation/en" \
  --db-dir "$HOME/.local/share/pi/unity-docs/6000.4.7f1" \
  --version 6000.4.7f1 \
  --yes

python3 scripts/unity_docs_db.py build \
  --source "/Applications/Unity/Hub/Editor/6000.4.7f1/Unity.app/Contents/Documentation/en" \
  --db-dir "$HOME/.local/share/pi/unity-docs/6000.4.7f1" \
  --version 6000.4.7f1 \
  --force \
  --progress

Configuration is stored at:

~/.pi/unity-docs/config.json

The generated database is named unity_docs.sqlite inside the selected database directory.

Multiple Unity versions

Each Unity editor version should use its own database directory, for example:

# Windows
%LOCALAPPDATA%/pi/unity-docs/6000.4.7f1
%LOCALAPPDATA%/pi/unity-docs/6000.5.2f1

# macOS/Linux
~/.local/share/pi/unity-docs/6000.4.7f1
~/.local/share/pi/unity-docs/6000.5.2f1

configure and build record core Unity databases by version under config.databases. The most recently configured or built version becomes the global fallback activeVersion, but project-aware queries should prefer --project <unity-project-path> so the docs version is read from ProjectSettings/ProjectVersion.txt. All configured core Unity databases are also exposed as docsets named unity-<version> for explicit multi-version queries.

When an exact project patch version is not configured, project-aware queries fall back only within the same Unity major/minor line:

1. exact version, for example 6000.4.7f1
2. configured line database, for example 6000.4.x or 6000.4
3. nearest configured patch in the same line, preferring the highest patch less than or equal to the project patch

Queries do not silently fall forward to a different minor line such as 6000.5.x; pass an explicit --docset/--docsets selector if that is intentional. Results include requestedVersion and versionMatch metadata when a project/version selector is used.

macOS/Linux examples (use python instead of python3 on Windows unless PI_UNITY_DOCS_PYTHON selects another interpreter):

python3 scripts/unity_docs_db.py search "Physics.Raycast" --project "/path/to/UnityProject"
python3 scripts/unity_docs_db.py search "Physics.Raycast" --docset unity-6000.4.7f1
python3 scripts/unity_docs_db.py search "Physics.Raycast" --docsets unity-6000.4.7f1,input-system

Tools exposed to pi

• unity_docs_info — show configuration and database status.
• unity_docs_search — full-text search over section-level Unity docs.
• unity_docs_symbol — exact/near-exact API symbol lookup.
• unity_docs_show — retrieve compact page sections.
• unity_docs_build_database — build/rebuild the core Unity docs cache when explicitly requested.
• unity_docs_build_docset — build/rebuild a package/plugin docset from Documentation~, a generic llms.txt manifest, public HTML pages, or C# XML docs when explicitly requested.
• unity_docs_validate — run representative validation queries across configured docsets.

Direct CLI usage

The examples below use python3 for macOS/Linux. On Windows, use python or the interpreter configured by PI_UNITY_DOCS_PYTHON.

python3 scripts/unity_docs_db.py info
python3 scripts/unity_docs_db.py build --source "<Unity Documentation/en>" --db-dir "<db-dir>" --force --progress
python3 scripts/unity_docs_db.py search "Physics.Raycast layerMask trigger" --limit 8
python3 scripts/unity_docs_db.py symbol "UnityEngine.Physics.Raycast"
python3 scripts/unity_docs_db.py show "ScriptReference/Physics.Raycast" --sections Declaration,Parameters,Returns,Description --max-chars 6000

Build a package docset from an explicit package docs source:

python3 scripts/unity_docs_db.py build-docset \
  --source "<package-root-or-Documentation~>" \
  --db-dir "<docset-db-dir>" \
  --docset-id "<docset-id>" \
  --force

Build a package docset from a Unity project's embedded packages or package cache:

python3 scripts/unity_docs_db.py build-docset \
  --project "<unity-project-path>" \
  --package-name "<package-name>" \
  --db-dir "<docset-db-dir>" \
  --force

Build from external documentation formats without keeping staged files in the package repo:

python3 scripts/unity_docs_db.py build-docset \
  --docset-id "<docset-id>" \
  --package-name "<package-name>" \
  --llms-url "<https://example.com/docs/llms.txt>" \
  --llms-section "<section heading>" \
  --db-dir "<docset-db-dir>" \
  --force

python3 scripts/unity_docs_db.py build-docset \
  --docset-id "<docset-id>" \
  --package-name "<package-name>" \
  --html-url "<https://example.com/documentation.html>" \
  --html-file "<path-to-local-documentation.html>" \
  --html-split-level 2 \
  --xml-doc "<path-to-csharp-xml-docs>" \
  --db-dir "<docset-db-dir>" \
  --force

Remote ingestion accepts HTTPS only, rejects credential-bearing URLs and non-public network destinations, limits each response to 10 MiB, and keeps links discovered in an llms.txt manifest on the manifest's origin. Use --html-file for intentional local HTML ingestion.

Build the rolling Unity CLI documentation from Unity's published Markdown manifest:

python3 scripts/unity_docs_db.py build-docset \
  --docset-id unity-cli \
  --package-name unity-cli \
  --title "Unity CLI" \
  --llms-url "https://docs.unity.com/en-us/unity-cli/llms.txt" \
  --db-dir "<unity-cli-docset-db-dir>" \
  --force

The manifest currently includes the CLI introduction, use guide, reference, and release notes. Pipeline command contracts should be indexed separately from an installed com.unity.pipeline package's Documentation~ directory so their package version remains explicit:

python3 scripts/unity_docs_db.py build-docset \
  --project "<unity-project-with-pipeline-installed>" \
  --package-name com.unity.pipeline \
  --docset-id "unity-pipeline-<package-version>" \
  --title "Unity Pipeline <package-version>" \
  --db-dir "<unity-pipeline-docset-db-dir>" \
  --force

Run representative validation queries across configured docsets:

python3 scripts/unity_docs_db.py validate --json

For project package resolution, embedded packages are checked before Library/PackageCache. If Packages/packages-lock.json contains a resolved version, that version is preferred before falling back to matching package-cache folders.

Add --json to query commands for machine-readable output. Build progress is emitted to stderr with --progress, so JSON stdout remains parseable.

Notes

• Requires Python 3.10+ and SQLite with FTS5 enabled. No third-party Python packages are required. The pi extension uses python on Windows and python3 on macOS/Linux; set PI_UNITY_DOCS_PYTHON to override the interpreter.
• Build time depends on disk speed. ScriptReference contains tens of thousands of pages.
• The database can be deleted at any time and rebuilt from the Unity install.

Native structured results

All seven tools declare a versioned output schema and return validated native facts independently of ordinary text/JSON presentation. See contracts, bounds and outcome policies. Search coverage distinguishes queried, excluded, missing and failed docsets; partial results do not prove absence. Keep a page's docset/version or the same explicit database selector when calling unity_docs_show.

Codemode returns the DTO directly; ctx.executeTool returns an outcome wrapper. Check ok separately from promise rejection. Failures with data can resolve ok:false; blocked/invalid/no-DTO calls can reject. Hooks may remove or alter structured data. Build failures can leave effects; never replay automatically.

const r = await tools.unity_docs_search({ query: "PlayerInput", docset: "input-system" });
text(r.ok ? { pages: r.rows.map(x => ({ page: x.pageId, docset: x.docsetId })), coverage: r.coverage } : r.error);