🎮 gdep — Game Codebase Analysis Tool

Understand a Unity/UE5/Axmol project in 0.5 seconds. Make Claude and Cursor read the actual code.

"If I modify this class, what breaks?" — answered in 3 seconds, grounded in source. Source-grounded: structural facts from C++ source and binary assets. Confidence tier (HIGH/MEDIUM/LOW) reported on every result.

Read this in other languages: 한국어 · 日本語 · 简体中文 · 繁體中文

---

✨ Why gdep?

Large game codebases are brutal:

• UE5 with 300+ Blueprints → "Where is this Ability actually called?" — half a day gone
• Unity with 50 Managers + Prefab refs → refactor triggers circular dep explosion
• "What breaks if I change this class?" → open files manually for 30 minutes

gdep answers all of this in under 0.5 seconds.

Measured Performance

Metric	Result	Notes
UE5 warm scan	0.46 s	2,800+ asset project
Unity warm scan	0.49 s	SSD, 900+ classes
Peak memory	28.5 MB	10× headroom vs target
MCP accuracy	5 / 5 (100%)	Code-based facts

Full details → docs/BENCHMARK.md · docs/mcp-benchmark.md

---

🤖 MCP Integration — Make AI Read Real Code

gdep ships an MCP server for Claude Desktop, Cursor, and any MCP-compatible agent.

Install in 1 line

npm install -g gdep-mcp

Configure your agent (copy-paste)

{
  "mcpServers": {
    "gdep": {
      "command": "gdep-mcp",
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

That's it. Your AI now has 30 game-engine-aware tools available on every conversation.

What changes with MCP

Without gdep:  "CombatCore probably has some Manager dependencies..." ← hallucination
With gdep:     Direct deps: 2 · Indirect: 200+ UI classes · Asset: prefabs/UI/combat.prefab

30 MCP Tools at a glance

Tool	When to use
get_project_context	Always call first — full project overview
wiki_search	Call before any analysis — search previously analyzed classes/assets by keyword (FTS5 BM25). Instant if cached
wiki_list	List all wiki nodes with staleness status — see what has already been analyzed
wiki_get	Read full content of a specific wiki node
wiki_save_conversation	Save agent conversation summary to wiki — persists session context, decisions, and findings across sessions. Creates discussed_in edges to referenced classes
analyze_impact_and_risk	Before modifying any class or method (method_name= for method-level callers; detail_level="summary" for quick count)
explain_method_logic	Internal control flow of a single method — Guard/Branch/Loop/Always. Supports C++ namespace-style functions. include_source=True appends method body
trace_gameplay_flow	Trace C++ → Blueprint call chains (summary=True for compact output)
inspect_architectural_health	Tech debt audit
explore_class_semantics	Unfamiliar class deep-dive. Default compact=True keeps output AI-friendly (~4–8 KB); include_source=True appends source code
suggest_test_scope	Which test files to run after modifying a class
suggest_lint_fixes	Lint issues with code fix suggestions (dry-run)
summarize_project_diff	Architecture-level summary of a git diff
get_architecture_advice	Full project diagnosis + LLM-powered advice
find_method_callers	Reverse call graph — who calls this method
find_call_path	Shortest call path between two methods (A → B, C#/Unity only)
find_class_hierarchy	Full inheritance tree — ancestors (parent chain) + descendants (subclass tree)
read_class_source	Return actual source code of a class or a specific method. method_name= to return only that method's body (token-efficient)
find_unused_assets	Unreferenced assets — Unity GUID scan / UE5 binary path reference scan
query_project_api	Search project API by class/method/property name with relevance scoring
detect_patterns	Detect design patterns in the codebase (Singleton, Subsystem, GAS, Component, etc.)
execute_gdep_cli	Raw access to all CLI features
find_unity_event_bindings	Inspector-wired methods (invisible in code search)
analyze_unity_animator	Animator state machine structure
analyze_axmol_events	Axmol EventDispatcher/Scheduler binding map
analyze_ue5_gas	GAS Abilities / Effects / Tags / ASC — with confidence header + IS-A asset role breakdown
analyze_ue5_behavior_tree	BehaviorTree asset structure
analyze_ue5_state_tree	StateTree asset structure
analyze_ue5_animation	ABP states + Montage + GAS Notifies
analyze_ue5_blueprint_mapping	C++ class → Blueprint impl mapping — with confidence header

Wiki — Analysis Result Cache

Analysis results are automatically saved to .gdep/wiki/ and indexed in SQLite + FTS5. The wiki accumulates knowledge across sessions — always wiki_search before running fresh analysis.

wiki_search("zombie ability") → instant result if already analyzed
wiki_list()                   → see all cached nodes with staleness status
wiki_get("class:ZombieChar")  → full cached analysis content

Key features:

• FTS5 full-text search with BM25 ranking — CamelCase-aware ("GameplayAbility" finds ULyraGameplayAbility)
• Dependency edges auto-extracted (inheritance, UPROPERTY, Behavioral Dependencies)
• Staleness detection: node flagged when source file changes since last analysis
• related=True on wiki_search expands results via dependency edges

UE5 Confidence Transparency

Every analyze_ue5_gas and analyze_ue5_blueprint_mapping response starts with:

> Analysis method: cpp_source_regex + binary_pattern_match
> Confidence: **MEDIUM**
> Coverage: 4633/4633 assets parsed (100.0%)
> UE version: 5.6 (validated)

gdep init generates a .gdep/AGENTS.md that tells AI agents exactly when to trust gdep results (HIGH = trust fully, MEDIUM = reliable, LOW = verify source) and when to read source files directly.

Full MCP setup → gdep-cli/gdep_mcp/README.md

---

📦 Installation

Prerequisites

Item	Version	Purpose
Python	3.11+	CLI · MCP server
.NET Runtime	8.0+	C# / Unity project analysis

One-click (Recommended)

# Windows
install.bat

# macOS / Linux
chmod +x install.sh && ./install.sh

Manual

cd gdep-cli && pip install -e .

---

🚀 Quick Start

gdep detect {path}                          # auto-detect engine
gdep scan {path} --circular --top 15        # structure overview
gdep init {path}                            # create .gdep/AGENTS.md for AI agents
gdep advise {path}                          # architecture diagnosis + advice

After gdep init, Claude / Cursor / Gemini automatically read the project context and know which gdep tools to call for which questions.

---

🖥️ Web UI — Visual Analysis in Your Browser

gdep ships a browser UI for interactive, visual analysis — no terminal required after setup.

Step 1 — Install (run once from project root)

install.bat          # Windows
./install.sh         # macOS / Linux

Step 2 — Launch

run.bat              # Windows — opens backend + frontend in two separate terminals automatically
./run.sh             # macOS/Linux — Terminal 1: backend  (http://localhost:8000)
./run_front.sh       # macOS/Linux — Terminal 2: frontend (http://localhost:5173)

Open http://localhost:5173 → point the sidebar to your project's source folder.

What you get:

• Interactive dependency graphs and call-flow visualization
• Class browser with impact analysis and lint
• AI chat agent that reads your actual codebase (tool-calling)
• Engine-specific explorers: GAS · Blueprint mapping · Animator · BehaviorTree · StateTree

UI language: English and Korean only · Local LLM: Ollama supported · Non-commercial, features may not be perfect

Full documentation → gdep-cli/web/README.md

---

🎯 Command Reference

Command	Summary	When to Use
detect	Auto-detect engine type	Before first analysis
scan	Coupling · Cycles · Dead code	Understand structure, before refactor
describe	Class detail + full inheritance chain + Blueprint impl + AI summary	Unfamiliar class, code review
flow	Method call chain (C++→BP boundary)	Bug tracing, flow analysis
impact	Change impact reverse-trace	Safety check before refactoring
method-impact	Reverse-trace callers of a specific method	Before modifying a method, find all call sites
path	Shortest call path between two methods (BFS, C#/Unity only)	Trace how A connects to B
test-scope	Test files to run after modifying a class	Before merging, CI planning
watch	Live file-change monitor (impact+test+lint)	During active development
lint	Game-specific anti-pattern scan (+ --fix)	Quality check before PR
advise	Full architecture diagnosis + LLM advice	Architecture review, tech debt
graph	Dependency graph export	Documentation, visualization
diff	Dependency diff before/after commit	PR review, CI gate
init	Create AI Agent context file	AI coding assistant setup
context	Print project context	Copy-paste to AI chat
hints	Manage singleton hints	Improve flow accuracy
config	LLM configuration	Before using AI summary features

📖 Command Details

scan

gdep scan {path} [options]

Option	Description
--circular	Detect circular dependencies
--dead-code	Detect unreferenced classes
--deep	Deep analysis including method bodies
--include-refs	Include Prefab/Blueprint back-references
--top N	Show top N by coupling (default: 20)
--format json	JSON output (for CI/Agent)

flow — traces C++ → Blueprint boundaries

gdep flow {path} --class <Class> --method <Method> [--depth N]

└── UARGamePlayAbility_BasicAttack.ActivateAbility
    ├── CommitAbility ○
    ├── BP_GA_BasicAttack_C.K2_ActivateAbility ○ [BP]   ← Blueprint entry
    └── BP_GA_HeavyAttack_C.K2_ActivateAbility ○ [BP]

test-scope — find test files affected by a class change

gdep test-scope {path} <ClassName>
gdep test-scope {path} <ClassName> --format json   # CI pipeline output
gdep test-scope {path} <ClassName> --depth 5       # broader search

watch — live monitor for file changes

gdep watch {path}                        # watch whole project
gdep watch {path} --class CombatManager  # only watch files related to class
gdep watch {path} --debounce 2.0         # adjust debounce (seconds)

On every save, instantly prints: impact count · test file count · lint warnings.

advise — architecture diagnosis

gdep advise {path}                        # full project diagnosis
gdep advise {path} --focus CombatManager  # class-focused diagnosis
gdep advise {path} --format json          # CI/MCP output

Without LLM configured: structured data report (cycles/coupling/dead-code/lint). With LLM configured: IMMEDIATE / MID-TERM / LONG-TERM natural-language advice.

lint — 19 game-engine anti-pattern rules

gdep lint {path}                # scan
gdep lint {path} --fix          # scan + code fix suggestions (dry-run, no file changes)

Rule ID	Engine	Description
UNI-PERF-001	Unity	GetComponent/Find in Update
UNI-PERF-002	Unity	new/Instantiate in Update
UNI-ASYNC-001	Unity	Coroutine while(true) without yield
UNI-ASYNC-002	Unity	FindObjectOfType/Resources.Load in Coroutine
UE5-PERF-001	UE5	SpawnActor/LoadObject in Tick
UE5-PERF-002	UE5	Synchronous LoadObject in BeginPlay
UE5-BASE-001	UE5	Missing Super:: call
UE5-GAS-001	UE5	Missing CommitAbility() in ActivateAbility()
UE5-GAS-002	UE5	Expensive world queries in GAS Ability
UE5-GAS-003	UE5	Excessive BlueprintCallable (>10)
UE5-GAS-004	UE5	Missing const on BlueprintPure method
UE5-NET-001	UE5	Replicated property without ReplicatedUsing callback
AXM-PERF-001	Axmol	getChildByName/Tag in update()
AXM-MEM-001	Axmol	retain() without release()
AXM-EVENT-001	Axmol	addEventListenerWith* without removeEventListener
UE5-BP-001	UE5	Blueprint references a C++ class not found in source (orphan reference)
UE5-BP-002	UE5	Blueprint K2 override references a deleted/changed C++ function
UNI-ASSET-001	Unity	Prefab script reference broken (.meta GUID mismatch)
GEN-ARCH-001	Common	Circular dependency

---

🎮 Supported Engines

Engine	Class Analysis	Flow Analysis	Back-refs	Specialized
Unity (C#)	✅	✅	✅ Prefab/Scene	UnityEvent, Animator
Unreal Engine 5	✅ UCLASS/USTRUCT/UENUM	✅ C++→BP	✅ Blueprint/Map	GAS, BP mapping, BT/ST, ABP/Montage
Axmol / Cocos2d-x (C++)	✅ Tree-sitter	✅	—	EventDispatcher/Scheduler bindings
.NET (C#)	✅	✅	—
Generic C++	✅	✅	—

---

🔄 Representative Workflows

Onboarding an unfamiliar codebase

gdep init {path}
gdep scan {path} --circular --top 20
gdep describe {path} CombatManager --summarize
gdep flow {path} --class CombatManager --method ExecuteAction

UE5 GAS end-to-end

gdep describe {path} UARGameplayAbility_Dash
gdep flow {path} --class UARGameplayAbility_Dash --method ActivateAbility

Pre-refactor safety check

gdep impact {path} CombatCore --depth 5
gdep test-scope {path} CombatCore
gdep lint {path} --fix
gdep diff {path} --commit HEAD

Architecture review

gdep advise {path}
gdep advise {path} --focus BattleManager

CI quality gate

gdep diff . --commit HEAD~1 --fail-on-cycles
gdep lint . --format json > lint_report.json
gdep test-scope . ChangedClass --format json > test_scope.json

Active development (live feedback)

gdep watch {path} --class CombatManager
# → On every save: impact count · test files · lint warnings

---

⚙️ C# Parser (gdep.dll)

Ships as an OS-agnostic single DLL — identical behavior on Windows · macOS · Linux.

dotnet publish -c Release --no-self-contained -o publish_dll

Detection priority: $GDEP_DLL env → publish_dll/gdep.dll → publish/gdep.dll → legacy binary

---

MCP Server → gdep-cli/gdep_mcp/README.md CI/CD Integration → docs/ci-integration.md Performance Benchmark → docs/BENCHMARK.md MCP Token & Accuracy → docs/mcp-benchmark.md