ArTchie Studios
ArTchie-Bedder-Suite / Docs / Atlas

Atlas Guide — project map, search, graph, trace

Plain English first. Sharp edges after.

1. What this is / is not

Atlas is a map of this Unity project. It indexes C# scripts, scenes, prefabs, ScriptableObjects, asmdefs, shaders, and MonoBehaviours into a knowledge graph you can search, graph, and trace. Mechanical path always works. Fully native Unity Editor APIs. No extras required to rebuild, search, open a symbol, or read the cache.

It is not Charter (game plans). It is not Scribe (comment banners). It is not Folio (markdown viewer). It is not ArTchie AI (companion chat). Atlas is Unity-only by design — it does not invent embeddings, multi-language world models, or a second store kit. Soft/optional Unity AI Assistant tools compile only when that package is present. ArTchie AI uses Atlas when both are present; neither kit requires the other.

2. Open it

Everything hangs under:

ArTchie / Atlas / …

Job Click
Search the project map ArTchie / Atlas / Codebase
GraphView of selection / hits + neighbors ArTchie / Atlas / Graph
Who-calls / what-it-calls ArTchie / Atlas / Trace
Counts, modules, entry points, hotspots, dead methods ArTchie / Atlas / Architecture
Full walk + save cache ArTchie / Atlas / Rebuild Index

Window tabs: Atlas Codebase · Atlas Graph · Atlas Trace · Atlas Architecture. Rebuild Index has no window (progress bar only).

If a README still says Atlas / … without the ArTchie/ prefix, the README is stale — trust the menu in Unity.

3. First five minutes

  1. Make sure com.artchie.atlas is in the project (Packages/unity-atlas or a file: entry in Packages/manifest.json). Open Unity. Wait for import. Check the Console for red errors.
  2. Click ArTchie / Atlas / Rebuild Index. Wait for the progress bar. Atlas walks Assets/ and embedded Packages/, then writes the cache.
  3. Click ArTchie / Atlas / Codebase. Status should show node/edge counts and an indexed time — not “No index.”
  4. Type a class or file name you know (example: Player). Toggle chips if you want only Class / Method / File.
  5. Click a result (snippet appears). Double-click or press Enter / click Open at symbol — the script opens at that line.

That is enough. Graph, Trace, and Architecture use the same index. Optional Unity AI tools come later — never required for search.

Folders whose names end with ~ are skipped on purpose (same rule Unity uses). Charter Genre Blueprints templates live in Blueprints/stubs~ — they should not show up in Search after Rebuild.

4. The meat

Where the index lives

Cache is project-local, not inside the package:

<project>/Library/Atlas/graph.json

Also used: Library/Atlas/api-out.json when headless/CLI API writes output. Delete Library/ and you lose the cache — run Rebuild Index again. The package itself never ships the graph.

What Rebuild walks

  1. AssetDatabase + GUID + GetDependencies for files, scenes, prefabs, SOs, shaders, asmdefs (and related Editor assets Atlas knows: .cs .unity .prefab .asset .asmdef .shader .hlsl .compute .cginc .uxml .uss).
  2. TypeCache / reflection on Editor + player assemblies (skips UnityEngine / UnityEditor / System).
  3. C# source scan for DEFINES, CALLS, IMPORTS, inheritance, Unity messages.
  4. asmdef → Module nodes; assembly references → IMPORTS.
  5. Prefab / SO SerializedObject object fields → REFERENCES / SERIALIZED_ON. Scenes → IN_SCENE.

Skips: Library/, Temp/, obj/, PackageCache, .git/, node_modules/, plus a root .gitignore if present (see AtlasIgnore). Also skips any path segment that ends in ~ — Unity’s own ignore rule. AtlasIgnore.IsIgnored returns true; AtlasIndexer.Walk does not descend those folders. Charter Genre Blueprints templates live under Blueprints/stubs~ so they do not compile into a buyer project and do not clutter Atlas Search.

Incremental refresh

After AssetDatabase imports/moves/deletes (and after compile), Atlas marks dirty paths and refreshes. Windows also have a Rebuild Index button for a full walk. If incremental fails, Atlas falls back to a full rebuild. Empty cache → EnsureLoaded rebuilds on first use.

Codebase window

  • Search: plain words, path, GUID, or prefixes t:Class / t:Method / f:Assets/Scripts.
  • Chips (EditorPrefs Atlas.Chip.*): Class · Method · File · Scene · Prefab · SO · Module · Interface.
  • Extra row: scope path filter, min deg / max structural degree, camelCase / snake_case aware.
  • Select → ping + numbered snippet. Double-click / Enter / Open at symbol → AssetDatabase.OpenAsset at the line.

Graph window

Native GraphView. Follow Project selection (toggle) or type a search. Label chips. Hops 1–3. Click = ping, double-click = open.

Trace window

Pick a Class / Method symbol. Direction: both / inbound / outbound. Depth 1–5. Path list + mini graph. Double-click a path row to open that hop.

Architecture window

Schema counts, asmdefs / modules, entry scenes + runtime entry flags, structural hotspots, assembly clusters.

Dead methods (Architecture foldout) = methods with zero inbound CALLS. The foldout HelpBox says the same.

  • Unity messages, tests, and entry/menu points are left off the list.
  • A call through a field counts: world.Get(...) is a CALLS edge to Get.
  • new Vector3( / new Ns.Type( is a constructor, not a method named Vector3 — Atlas does not record it as a call.
  • Several methods with the same name in one assembly: Atlas draws CALLS to each (cap 16), not a weak USAGE-only edge.
  • A name that never appears as ident( still looks dead. That can be a true unused method. Rebuild Index after scripts compile.

Empty / first-run (no index): title No index yet + HelpBox (click Rebuild Index) + miniLabel (ArTchie / Atlas / Rebuild Index, cache Library/Atlas/graph.json). Same empty pattern on Codebase / Graph / Trace / Architecture.

Soft Unity AI (optional)

Atlas.Editor.asmdef gates Assistant tool registration with:

com.unity.ai.assistant >= 0.1.0 → UNITY_AI_ASSISTANT

When present, AtlasAssistantTools registers Search / Trace / Snippet / Architecture / DeadMethods for Unity AI Assistant. When missing, Atlas menus and AtlasApi still work — zero hard dependency on Unity AI. No pasted key.

Missing optional Unity AI (HelpBox)

  • Unity AI absent: Info HelpBox on Codebase / Graph / Trace / Architecture — not in this project (com.unity.ai.assistant); optional Assistant tools unavailable; Rebuild Index, search, and graph still work — no key needed.
  • No CLI Detect in Atlas: logged-in CLIs live in Scribe / Charter / ArTchie AI — Detect paths there, then sign in. Prefer Detect over pasting a key.
  • Mechanical first: Rebuild Index / search / graph / open-at-symbol never blocked by missing Unity AI.

Soft pair: ArTchie AI

Install Atlas if you want companion chat to use the project map. Chat still runs without Atlas (map tools return kit not loaded). Atlas alone never requires ArTchie AI or a pasted key.

Soft friends (others use Atlas)

  • Scribe may enrich Used by from the Atlas index via reflection when present.
  • Bedder may probe Atlas by reflection only — never a compile hard-dep.
  • Charter / Folio / Anvil / Rivet do not need Atlas.

5. Common stuck

  1. Menus say Atlas / … without ArTchie/ — stale README. Trust Unity: ArTchie / Atlas / ….
  2. Empty results / “No index” — run ArTchie / Atlas / Rebuild Index, wait, then search again. Confirm Library/Atlas/graph.json exists.
  3. I don’t see ArTchie / Atlas — package not imported, asmdef error, or wrong project. Check Console and Packages/manifest.json for com.artchie.atlas.
  4. Double-click does nothing useful — pick a hit with a real Assets/… path (or Package path Atlas indexed). Ping/Open need a loadable asset.
  5. Dead methods list empty, huge, or flags Get that I call every frame — Rebuild Index after scripts compile. Zero-CALLS candidates skip Unity messages / tests / entries. Calls through a field (world.Get) count; new Vector3( is not a method. Same-name methods in one assembly each get CALLS (cap 16). If a name never appears as ident(, it stays dead — that can be a true unused method.
  6. Search shows Charter Genre Blueprints stubs / files under stubs~ — it should not. Atlas skips any path segment ending in ~ (Unity’s ignore). Rebuild Index. If hits remain, the path is not actually under a ~ folder.
  7. Unity AI tools missing / ArTchie AI chat won’t use the map — Unity AI is optional (HelpBox; no pasted key). Atlas has no CLI Detect (use Scribe / Charter / ArTchie AI Detect paths). Rebuild Index, search, and graph still work. ArTchie AI is a sibling kit — install it for companion chat; it does not have to be present for Atlas.

6. For pros

Package + asmdef

  • Package: com.artchie.atlas · Unity 2021.3+ · asmdef Atlas.Editor
  • Native lock: AssetDatabase, TypeCache, CompilationPipeline, MonoScript, SerializedObject, EditorWindow, UIToolkit, IMGUI, UnityEditor.Experimental.GraphView
  • Cache API: AtlasStore.CacheDir / CachePath → Library/Atlas/graph.json (format blob via JsonUtility)
  • Persist fields: format, version, builtUtc, projectName, incremental, nodes, edges

Ignore + DeadMethods (Fable)

  • AtlasIgnore.IsIgnored — after slash-normalize, if any path segment ends with ~, ignored. Source of truth for files.
  • AtlasIndexer.Walk — does not descend a child directory whose name ends with ~.
  • AtlasSourceScan.ScanBody — skip new Type( / new Ns.Type( (PrecededByNewKeyword look-back). Constructors are not CALLS. Scanner-native, no Roslyn.
  • AtlasIndexer.LinkCsGraph — each recorded ident( becomes CALLS. Prefer same-assembly hits; if several, CALLS to each (cap 16) instead of USAGE-only. Instance-field receivers (world.Get) count.
  • AtlasQuery.DeadMethods — inbound CALLS == 0; skip UnityMessage / EntryPoint / Test / Main. Unchanged contract; the scan/link fixes are what stop false-dead Get/Set/Rebuild.

AtlasApi (JSON strings)

Atlas.AtlasApi.Status()
Atlas.AtlasApi.RebuildIndex()
Atlas.AtlasApi.Search("t:Class player", 20)
Atlas.AtlasApi.Trace("MyClass.MyMethod", "both", 2, 40)
Atlas.AtlasApi.Architecture()
Atlas.AtlasApi.DeadMethods(60)
Atlas.AtlasApi.Snippet("MyClass.MyMethod", 8)
Atlas.AtlasApi.GraphPath   → Library/Atlas/graph.json

Headless:

Unity -batchmode -quit -projectPath X -executeMethod Atlas.AtlasApi.Cli
  -atlas-cmd rebuild|status|search|trace|arch|dead|snippet
  -atlas-arg "query or symbol" [-atlas-dir inbound|outbound|both]
  [-atlas-depth N] [-atlas-limit N] [-atlas-out path.json]

Default -atlas-out: Library/Atlas/api-out.json. Agents can also parse graph.json directly.

versionDefines

com.unity.ai.assistant >= 0.1.0 → UNITY_AI_ASSISTANT

AtlasAssistantTools compiles only behind that define. When absent, windows show the Info HelpBox from AtlasOptionalAiGui. No pasted API key. No MCP required for Editor use. No CLI Detect in this kit.

Design bounds (do not invent)

Atlas indexes this Unity project. Do not document fictional multi-language corpora, embedding stores, or a third kit. Scribe/Charter soft friends stay reflection-soft. ArTchie AI stays the HARD consumer.

Canonical base

artchie-RECONCILED-20260822-2107. Package README + this Guide.

Kit When you want it
Suite Map Which ArTchie pile does what · Guides/Guide-Suite-Map.md
ArTchie AI Companion chat — uses Atlas when both present; neither required; never require a pasted key
Scribe Soft “Used by” from Atlas when present; comment / document scripts
Charter Game plans (does not need Atlas)
Folio Read markdown in the Editor
Anvil / Rivet Project health · daily Editor chores
Bedder In-player IDE; may probe Atlas by reflection only

Rebuild first. Search second. AI is optional on top — and AI needs this map.

Source in the box: Assets/ArTchie Studios/ArTchie-Suite/com.artchie.atlas/Documentation/Guide-Atlas.md