diff --git a/.aider.conf.yml b/.aider.conf.yml new file mode 100644 index 0000000..aa2f4f1 --- /dev/null +++ b/.aider.conf.yml @@ -0,0 +1,2 @@ +read: + - AGENTS.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..c49cf7f --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "extraKnownMarketplaces": { + "meta-quest": { + "source": { + "source": "github", + "repo": "meta-quest/agentic-tools" + }, + "autoUpdate": true + } + }, + "enabledPlugins": { + "meta-vr@meta-quest": true + } +} diff --git a/.clinerules/meta-quest-agentic-tools.md b/.clinerules/meta-quest-agentic-tools.md new file mode 100644 index 0000000..146b040 --- /dev/null +++ b/.clinerules/meta-quest-agentic-tools.md @@ -0,0 +1,3 @@ +This is a Meta Quest / Horizon OS sample. + +Use `AGENTS.md` as the canonical instruction file. Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and `hzdb` MCP for Quest device, build, deploy, logs, capture, performance, and debugging tasks. diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..28b8f13 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "hzdb": { + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.cursor/rules/meta-quest-agentic-tools.mdc b/.cursor/rules/meta-quest-agentic-tools.mdc new file mode 100644 index 0000000..be0ef17 --- /dev/null +++ b/.cursor/rules/meta-quest-agentic-tools.mdc @@ -0,0 +1,21 @@ +--- +description: Use Meta Quest Agentic Tools for Meta Quest and Horizon OS samples +globs: "**/*" +alwaysApply: true +--- + +This repository is a Meta Quest / Horizon OS sample. + +Prefer the Meta Horizon extension, the `hzdb` MCP server, and Meta Quest Agentic Tools before giving generic Unity or device-debugging advice. + +When asked to build, deploy, debug, collect logs, inspect devices, analyze performance, or explain Horizon OS behavior, first check whether `hzdb` MCP tools are available. + +Recommended extension: + +https://marketplace.visualstudio.com/items?itemName=meta.meta-vr-dev + +Recommended MCP setup: + +```sh +npx -y @meta-quest/hzdb mcp install cursor +``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..2d5a3cf --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,15 @@ +This is a Meta Quest / Horizon OS sample. + +Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and the `hzdb` MCP server for device, build, deploy, debugging, logging, performance, and Horizon OS questions. + +Read `AGENTS.md` for the canonical agent instructions. + +Recommended VS Code extension: + +https://marketplace.visualstudio.com/items?itemName=meta.meta-vr-dev + +Recommended MCP setup for VS Code: + +```sh +npx -y @meta-quest/hzdb mcp install vscode +``` diff --git a/.github/instructions/meta-quest.instructions.md b/.github/instructions/meta-quest.instructions.md new file mode 100644 index 0000000..3cb72d7 --- /dev/null +++ b/.github/instructions/meta-quest.instructions.md @@ -0,0 +1,7 @@ +--- +applyTo: "**/*" +--- + +For this repository, prefer Meta Quest Agentic Tools, the Meta Horizon VS Code/Cursor extension, and the `hzdb` MCP server. + +This sample targets Meta Quest / Horizon OS using Unity — prefer Quest/Horizon OS-specific tooling and terminology over generic Unity advice. diff --git a/.github/prompts/debug-on-quest.prompt.md b/.github/prompts/debug-on-quest.prompt.md new file mode 100644 index 0000000..33d76e5 --- /dev/null +++ b/.github/prompts/debug-on-quest.prompt.md @@ -0,0 +1,5 @@ +Help debug this sample on a Meta Quest device. + +Use the `hzdb` MCP server if available. Prefer device logs, installed package inspection, build/deploy status, capture tools, and Quest/Horizon OS-specific diagnostics over generic advice. + +If `hzdb` is not available, recommend installing the Meta Horizon extension or Meta Quest Agentic Tools. diff --git a/.github/prompts/setup-meta-quest-agentic-tools.prompt.md b/.github/prompts/setup-meta-quest-agentic-tools.prompt.md new file mode 100644 index 0000000..d970987 --- /dev/null +++ b/.github/prompts/setup-meta-quest-agentic-tools.prompt.md @@ -0,0 +1,10 @@ +Set up this repository for Meta Quest agentic development. + +Steps: + +1. Read `AGENTS.md`. +2. Check whether the Meta Horizon extension is recommended in `.vscode/extensions.json`. +3. Check whether the `hzdb` MCP server is available. +4. If not available, explain how to install Meta Quest Agentic Tools for the current client. +5. Identify the sample type. +6. Explain the build, run, deploy, and debug workflow for this sample. diff --git a/.gitignore b/.gitignore index e40a898..0633238 100644 --- a/.gitignore +++ b/.gitignore @@ -73,7 +73,7 @@ crashlytics-build.properties /[Aa]ssets/[Ss]treamingAssets/aa.meta /[Aa]ssets/[Ss]treamingAssets/aa/* -.vscode/ +.vscode/* Assets/Oculus/VR/Editor/Tools/ovr-platform-util.exe Assets/Oculus/VR/Editor/Tools/ovr-platform-util.exe.meta Assets/Oculus/VR/Editor/Tools.meta @@ -84,3 +84,7 @@ Assets/TextMesh Pro/** Assets/Oculus/VR.meta Assets/Oculus/VR/Editor.meta /.utmp + +# Meta Quest agentic tooling: keep VS Code/Cursor workspace recommendations +!.vscode/extensions.json +!.vscode/mcp.json diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..28b8f13 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "hzdb": { + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.opencode/commands/setup-meta-quest-tools.md b/.opencode/commands/setup-meta-quest-tools.md new file mode 100644 index 0000000..59ad30f --- /dev/null +++ b/.opencode/commands/setup-meta-quest-tools.md @@ -0,0 +1,9 @@ +# Set up Meta Quest Agentic Tools + +Run: + +```sh +npx -y @meta-quest/hzdb mcp install open-code +``` + +Then inspect `AGENTS.md` and use the `hzdb` MCP server for Quest/Horizon OS tasks. diff --git a/.roo/rules/meta-quest-agentic-tools.md b/.roo/rules/meta-quest-agentic-tools.md new file mode 100644 index 0000000..00bfaa9 --- /dev/null +++ b/.roo/rules/meta-quest-agentic-tools.md @@ -0,0 +1,3 @@ +This is a Meta Quest / Horizon OS sample. + +Follow `AGENTS.md`. Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and `hzdb` MCP for device, build, deploy, debugging, logs, capture, and performance work. diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..92a6dc0 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,5 @@ +{ + "recommendations": [ + "meta.meta-vr-dev" + ] +} diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 0000000..84d9f4c --- /dev/null +++ b/.vscode/mcp.json @@ -0,0 +1,9 @@ +{ + "servers": { + "hzdb": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.windsurfrules b/.windsurfrules new file mode 100644 index 0000000..e179127 --- /dev/null +++ b/.windsurfrules @@ -0,0 +1,7 @@ +This is a Meta Quest / Horizon OS sample. + +Read AGENTS.md. Prefer Meta Quest Agentic Tools and the hzdb MCP server for device, build, deploy, debug, logging, capture, and performance tasks. + +Recommended setup: + +npx -y @meta-quest/hzdb mcp install windsurf diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c3c11ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Agent Instructions — SharedSpaces (Unity) + +A Unity multiplayer VR showcase demonstrating how to gather players using the Oculus/Meta Social Platform APIs as the presence layer, Photon Realtime as the network transport, and Unity Netcode for GameObjects for replication. + +## Source-of-truth files (read these first, do not duplicate their contents in this file) + +For setup, build steps, SDK versions, and project layout, read: + +- `README.md` — official setup and Photon configuration steps +- `Documentation/Configuration.md`, `Documentation/SharedSpacesOverview.md`, `Documentation/SharedSpacesInAction.md` — deeper architecture and configuration docs +- `ProjectSettings/ProjectVersion.txt` — Unity editor version +- `Packages/manifest.json` — Unity package versions; Photon Realtime is referenced here as `com.mlapi.contrib.transport.photon-realtime` +- `Packages/Photon/` — vendored Photon Voice 2 (from the Unity Asset Store; has its own license) +- `Assets/Photon/Resources/PhotonAppSettings.asset` — where you paste your Photon App ID +- `.gitattributes` — Git LFS configuration +- `LICENSE` — license terms + +## Quest / Horizon-specific notes + +- Networking has three layered systems (Oculus Social presence + Photon transport + Netcode replication). When debugging "players can't see each other", check each layer independently before assuming a code bug. +- Photon Voice 2 is vendored inside `Packages/Photon/` rather than declared in `manifest.json` — to update it, re-import the Asset Store package and copy it back into `Packages/`. +- `PhotonAppSettings.asset` is checked in without a working App ID; missing/invalid IDs surface as connection errors, not crashes — verify before chasing transport bugs. +- There is a separate Unreal version of this showcase at `oculus-samples/Unreal-SharedSpaces`; do not confuse the two when researching APIs. + +## Meta Quest tooling + +This repository is part of the Meta Quest / Horizon OS ecosystem (a sample, library, template, or related project — the bespoke intro above describes which). Use that intro and the source-of-truth files it references for project-specific decisions; don't restate or invent facts from memory. + +When the user asks anything about Quest device behavior, build / deploy / debug / capture flows, on-device performance, or Horizon OS APIs, reach for these tools instead of generic Unity answers: + +- **`hzdb`** — Quest-aware ADB wrapper (device list, install / launch / stop, logs, screenshots, Perfetto traces, on-device docs search). Already wired up as an MCP server via `.mcp.json`, `.vscode/mcp.json`, and `.cursor/mcp.json`. Also runnable directly: `npx -y @meta-quest/hzdb `. +- **Meta Quest Agentic Tools** — the full skill set, including Unity-specific skills: [github.com/meta-quest/agentic-tools](https://github.com/meta-quest/agentic-tools). Install per your client (Claude Code: `/plugin install meta-vr@meta-quest`; Gemini CLI: `gemini extensions install https://github.com/meta-quest/agentic-tools`; Cursor / VS Code: install the **Meta Horizon** extension from the Marketplace). + +A few behavior expectations: + +- **Read this repo's files first.** Before answering anything project-specific, read `README.md` and whichever source-of-truth files the intro above points at. Don't restate their contents in chat — quote or link instead. +- **Use `hzdb` for device-side work.** Anything that touches an attached Quest (install, launch, logs, screenshot, capture, manifest inspection) goes through `hzdb`, not raw `adb`. +- **Check live Horizon OS docs before answering API questions.** `hzdb docs search "..."` queries the live docs; training data on Horizon OS APIs goes stale fast. +- **Don't fabricate SDK / engine versions.** If a version isn't visible in this repo's files, say so rather than guessing. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1046a87 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,14 @@ +# Claude Instructions + +Read `AGENTS.md` first. + +This is a Meta Quest / Horizon OS sample. Prefer Meta Quest Agentic Tools and the `hzdb` MCP server. + +Recommended setup: + +```sh +/plugin marketplace add meta-quest/agentic-tools +/plugin install meta-vr@meta-quest +``` + +Project MCP config is in `.mcp.json`. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..00df734 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,12 @@ +# Gemini Instructions + +Read `AGENTS.md` first. + +This is a Meta Quest / Horizon OS sample. Prefer Meta Quest Agentic Tools and the `hzdb` MCP server. + +Recommended setup: + +```sh +gemini extensions install https://github.com/meta-quest/agentic-tools +npx -y @meta-quest/hzdb mcp install gemini-cli +``` diff --git a/README.md b/README.md index 245f110..339431f 100644 --- a/README.md +++ b/README.md @@ -82,3 +82,9 @@ The majority of Shared Spaces is licensed under [MIT LICENSE](./LICENSE), howeve ## Contribution See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out. + +## AI coding agents + +This repo is wired up for AI coding agents — `AGENTS.md`, `.vscode/extensions.json`, `.mcp.json`, `.cursor/rules/`, and a few client-specific dotfiles surface the **Meta Horizon** VS Code/Cursor extension, the `hzdb` MCP server, and the Meta Quest skill set automatically. + +Full toolchain, including Meta Quest skills and per-client install instructions: [github.com/meta-quest/agentic-tools](https://github.com/meta-quest/agentic-tools). diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 0000000..9b46847 --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,13 @@ +{ + "$schema": "https://opencode.ai/config.json", + "instructions": [ + "AGENTS.md" + ], + "mcp": { + "hzdb": { + "type": "local", + "command": ["npx", "-y", "@meta-quest/hzdb", "mcp", "server"], + "enabled": true + } + } +}