From a00f0259c3650d78c76d08732e9393485b223762 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 23 Feb 2026 16:46:57 +0100 Subject: [PATCH 1/2] docs: add Unity SDK architecture + coding agent guardrails --- .github/agent-docs/guardrails.md | 30 ++++++++ .github/copilot-instructions.md | 15 ++++ README.md | 4 ++ docs/architecture.md | 118 +++++++++++++++++++++++++++++++ 4 files changed, 167 insertions(+) create mode 100644 .github/agent-docs/guardrails.md create mode 100644 .github/copilot-instructions.md create mode 100644 docs/architecture.md diff --git a/.github/agent-docs/guardrails.md b/.github/agent-docs/guardrails.md new file mode 100644 index 000000000..b234ec3db --- /dev/null +++ b/.github/agent-docs/guardrails.md @@ -0,0 +1,30 @@ +# Coding Agent Guardrails (LootLocker Unity SDK) + +These rules exist to keep changes safe, reviewable, and aligned with how this repo ships. + +## Branching + PRs +- Never commit directly to `dev` or `main`. +- Create a work branch (e.g. `docs/...`, `fix/...`, `feat/...`). +- Open PRs targeting `dev` (never `main`). + +## Release / versioning prohibitions +Unless the task explicitly asks for it, do **not**: +- Create tags, GitHub Releases, or publish packages. +- Bump versions or edit release metadata (for example `package.json` version). + +## Change discipline +- Keep diffs minimal and scoped to the task. +- Do not move/rename files or restructure folders unless explicitly requested. +- Search before adding new helpers/utilities to avoid duplication. +- Avoid drive-by refactors (formatting, naming, reorganization) unless requested. + +## Runtime vs Editor boundary +- Runtime code must be build-safe (no unguarded `UnityEditor` dependencies). +- Put editor tooling under `Runtime/Editor/` (this repo’s editor-only area) and/or guard editor-only code with `#if UNITY_EDITOR`. + +## When unsure +If a change would require guessing architecture, conventions, or customer-facing API behavior: +- Stop and ask for clarification rather than inventing a new pattern. + +## Reference +- Architecture & structure overview: `docs/architecture.md` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..e0d6c2457 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,15 @@ +# Copilot / Coding Agent instructions (LootLocker Unity SDK) + +Follow these rules for any work in this repo: + +## Non-negotiables +- Never commit directly to `dev` or `main`. +- PRs must target `dev`. +- Do not tag/publish/create releases. +- Do not bump versions or edit release metadata (for example `package.json` version) unless explicitly asked. +- Keep diffs minimal; do not move/rename files unless explicitly requested. +- Search first to avoid duplicating helpers/utilities. + +## Architecture references +- Repo structure + “where do I implement X?”: `docs/architecture.md` +- Guardrails (agent operating rules): `.github/agent-docs/guardrails.md` diff --git a/README.md b/README.md index 719edf8ce..b0a11b56d 100644 --- a/README.md +++ b/README.md @@ -78,3 +78,7 @@ To set up the tests, you must add our package to the manifest.json `testables` u Once you have done this, you can go into Unity and go to `Window` -> `General` -> `Test Runner`. This will open a new window which should already include all the tests available, Then all you have to do is press `Run All` and the tests will begin. If you are running the tests towards the LootLocker production environment you will need to provide a username and password to an existing user either by setting the values directly in LootLockerTestConfigurationUser::GetProductionUser or via command line arguments -adminemail and -adminpassword. Bear in mind that your tests will be rate limited when running towards production (and in general this is a bad idea). + +## Internal developer docs +- Architecture & structure: [docs/architecture.md](docs/architecture.md) +- Coding Agent guardrails: [.github/agent-docs/guardrails.md](.github/agent-docs/guardrails.md) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..c7cd20431 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,118 @@ +# Unity SDK architecture & repo structure + +- Repo layout: **UPM package at repository root** (customers receive an `Assets/` wrapper via CI packaging). +- Public entrypoint: `Runtime/Game/LootLockerSDKManager.cs` + +For agent operating rules, see: `.github/agent-docs/guardrails.md`. + +## Repository map (root) +- `Runtime/` — Shippable SDK code (runtime + editor-guarded pieces). Main entrypoint is in `Runtime/Game/`. +- `Tests/` — Unity Test Runner tests and test utilities. +- `Samples~/` — UPM samples (example scenes/scripts). +- `Prefabs/` — Exported `.unitypackage` artifacts (not runtime code). +- `.github/` — Internal repo automation + agent docs (excluded from customer packaging). +- `docs/` — Internal developer documentation (excluded from customer packaging). +- `package.json` — UPM package manifest (do not bump version unless explicitly tasked). + +## Where the code lives + +### Public API surface +- `Runtime/Game/LootLockerSDKManager.cs` + - The user-facing SDK class. Most SDK features are exposed as static methods here. + - The class is `partial` and very large; changes here are inherently API-surface changes. + +### Runtime “core” services / transport +- `Runtime/Client/LootLockerHTTPClient.cs` — HTTP transport built on `UnityEngine.Networking.UnityWebRequest`. +- `Runtime/Client/LootLockerHttpRequestData.cs` — Request data model/formatting used by the HTTP client. +- `Runtime/Client/LootLockerHTTPExecutionQueueItem.cs` — Execution/queue bookkeeping for HTTP requests. +- `Runtime/Client/LootLockerRateLimiter.cs` — Client-side rate limiting. +- `Runtime/Client/LootLockerEndPoints.cs` + `Runtime/Client/EndPointClass.cs` — Endpoint path/method definitions. + +### Requests + response models +- `Runtime/Game/Requests/` — Feature-focused request code. + - Convention observed in this repo: many request files also define their **response DTOs** in the same file (e.g., classes deriving from `LootLockerResponse`). + +Shared response base + errors: +- `Runtime/Client/LootLockerResponse.cs` — Base response type + deserialization helper. +- `Runtime/Client/LootLockerErrorData.cs` — Error payload shape. +- `Runtime/Client/LootLockerRequestContext.cs` — Context attached to responses. + +### Serialization +- `Runtime/Client/LootLockerJson.cs` — Serialization wrapper. + - Uses Newtonsoft JSON when `LOOTLOCKER_USE_NEWTONSOFTJSON` is defined. + - Otherwise uses `Runtime/Libraries/ZeroDepJson/`. +- `Runtime/Libraries/ZeroDepJson/` — Built-in JSON implementation (no external dependency). + +### Session / player state (auth tokens, persistence) +- `Runtime/Client/LootLockerPlayerData.cs` — In-memory player/session token fields. +- `Runtime/Client/LootLockerStateData.cs` — Service that persists player state and reacts to session lifecycle events. +- `Runtime/Client/LootLockerStateWriter.cs` — `ILootLockerStateWriter` abstraction; default uses `PlayerPrefs` unless disabled. + +### Lifecycle + events +- `Runtime/Client/ILootLockerService.cs` — Service interface. +- `Runtime/Client/LootLockerLifecycleManager.cs` — Central manager that instantiates services and coordinates Unity lifecycle. +- `Runtime/Client/LootLockerEventSystem.cs` — Eventing used by services (e.g., session started/refreshed/ended). + +### Configuration +- `Runtime/Game/Resources/LootLockerConfig.cs` — ScriptableObject settings. + - Uses `Resources.Load` at runtime. + - Editor-only asset creation/editor integrations are guarded by `#if UNITY_EDITOR`. + +### Logging / utilities +- `Runtime/Game/LootLockerLogger.cs` — SDK logging. +- `Runtime/Game/LootLockerObfuscator.cs` — Sensitive log obfuscation. +- `Runtime/Game/Utilities/` — General helpers used by the SDK. + +### Editor tooling (repo’s “Editor” area) +- `Runtime/Editor/` — Editor-only tooling (LootLocker extension UI, log viewer, editor data, etc.). + - This is the effective “Editor/” boundary in this repo. + +### Tests +- `Tests/LootLockerTests/PlayMode/` — PlayMode tests + `PlayModeTests.asmdef`. +- `Tests/LootLockerTestUtils/` — Shared test configuration helpers + `LootLockerTestUtils.asmdef`. + +### Samples +- `Samples~/LootLockerExamples/` — UPM samples + `LootLockerExamples.asmdef`. + +## Architectural boundaries / invariants (observed) + +### Runtime must be build-safe +- Any `UnityEditor` usage is expected to be behind `#if UNITY_EDITOR` guards. +- Editor-only implementations should live under `Runtime/Editor/`. + +### Public API discipline +- Adding/changing public methods in `LootLockerSDKManager` changes the customer-facing surface area. +- Prefer keeping helper types/methods `internal`/`private` unless they are intentionally part of the public SDK. + +### Search-first to avoid duplication +- Requests, response DTOs, and shared helpers are frequently co-located (especially under `Runtime/Game/Requests/`). +- Before introducing new utilities or DTOs, search for existing equivalents. + +## Where do I implement X? + +| Change you want to make | Put it here (real paths in this repo) | +|---|---| +| Add/modify a customer-facing SDK method or its documentation | `Runtime/Game/LootLockerSDKManager.cs` | +| Add a new feature request (API call) | `Runtime/Game/Requests/*.cs` contains the DTO structs and their documentation and customer exposure is added through `Runtime/Game/LootLockerSDKManager.cs` and the necessary endpoint constants are added in `Runtime/Client/LootLockerEndPoints.cs` | +| Add/adjust response DTO fields for a request | Usually in the same `Runtime/Game/Requests/*.cs` file (classes deriving `LootLockerResponse`) | +| Add/adjust endpoint URL/method constants | `Runtime/Client/LootLockerEndPoints.cs` and/or `Runtime/Client/EndPointClass.cs` | +| Change HTTP behavior (retries, headers, request creation) | `Runtime/Client/LootLockerHTTPClient.cs` + `Runtime/Client/LootLockerHttpRequestData.cs` | +| Change serialization rules | `Runtime/Client/LootLockerJson.cs` (and `Runtime/Libraries/ZeroDepJson/` if not using Newtonsoft) | +| Change session/persistence behavior | `Runtime/Client/LootLockerStateData.cs`, `Runtime/Client/LootLockerStateWriter.cs`, `Runtime/Client/LootLockerPlayerData.cs` | +| Add/adjust config settings | `Runtime/Game/Resources/LootLockerConfig.cs` | +| Add editor window/extension UI | `Runtime/Editor/` | +| Add/adjust tests | `Tests/LootLockerTests/PlayMode/` (tests) and `Tests/LootLockerTestUtils/` (shared config) | +| Add/adjust samples | `Samples~/LootLockerExamples/` | + +## Common pitfalls +- Duplication: search under `Runtime/Game/Requests/` and `Runtime/Client/` before adding new helpers. +- Accidental API surface growth: avoid adding new `public` types/methods unless that is the goal. +- Drive-by refactors: keep PRs narrow; large reshuffles make review harder and increase risk. +- Editor leakage: keep `UnityEditor` references guarded and editor-only code inside `Runtime/Editor/`. + +## Links +- Coding Agent guardrails: `.github/agent-docs/guardrails.md` + +## Future expansion (placeholders) +- Build & test (to be filled by later tasks) +- CI packaging notes (to be filled by later tasks) From 5e7ed54d3c92d272be14e9bb603a6546faee243e Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Tue, 24 Feb 2026 11:37:24 +0100 Subject: [PATCH 2/2] docs: move agent docs under .github/instructions --- .github/copilot-instructions.md | 4 ++-- {docs => .github/instructions}/architecture.md | 0 .github/{agent-docs => instructions}/guardrails.md | 0 README.md | 4 ---- 4 files changed, 2 insertions(+), 6 deletions(-) rename {docs => .github/instructions}/architecture.md (100%) rename .github/{agent-docs => instructions}/guardrails.md (100%) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e0d6c2457..87d1a95a6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,5 +11,5 @@ Follow these rules for any work in this repo: - Search first to avoid duplicating helpers/utilities. ## Architecture references -- Repo structure + “where do I implement X?”: `docs/architecture.md` -- Guardrails (agent operating rules): `.github/agent-docs/guardrails.md` +- Repo structure + “where do I implement X?”: `.github/instructions/architecture.md` +- Guardrails (agent operating rules): `.github/instructions/guardrails.md` diff --git a/docs/architecture.md b/.github/instructions/architecture.md similarity index 100% rename from docs/architecture.md rename to .github/instructions/architecture.md diff --git a/.github/agent-docs/guardrails.md b/.github/instructions/guardrails.md similarity index 100% rename from .github/agent-docs/guardrails.md rename to .github/instructions/guardrails.md diff --git a/README.md b/README.md index b0a11b56d..719edf8ce 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,3 @@ To set up the tests, you must add our package to the manifest.json `testables` u Once you have done this, you can go into Unity and go to `Window` -> `General` -> `Test Runner`. This will open a new window which should already include all the tests available, Then all you have to do is press `Run All` and the tests will begin. If you are running the tests towards the LootLocker production environment you will need to provide a username and password to an existing user either by setting the values directly in LootLockerTestConfigurationUser::GetProductionUser or via command line arguments -adminemail and -adminpassword. Bear in mind that your tests will be rate limited when running towards production (and in general this is a bad idea). - -## Internal developer docs -- Architecture & structure: [docs/architecture.md](docs/architecture.md) -- Coding Agent guardrails: [.github/agent-docs/guardrails.md](.github/agent-docs/guardrails.md)