gdep 0.2.9

Game Engine Dependency & AI Analysis Tool

🎮 gdep — Game Codebase Analysis Tool

Analyze game client codebases directly from your terminal and AI Agent.

Supports Unity · Cocos2d-x · Unreal Engine 5 · .NET C# · Generic C++.

GitHub · MCP Setup · CI/CD Integration

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

---

📦 Installation

Prerequisites

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

pip install gdep

After installation, the gdep command is available globally.

For the MCP server (Claude Desktop / Cursor integration), also install:

npm install -g gdep-mcp

---

🚀 Quick Start

1. Detect Project

gdep detect {path}

2. Analyze Structure

gdep scan {path} --circular --top 15

┌─ scan results ───────────────────────────────────────┐
│ Files: 312  |  Classes: 847  |  Dead Code: 12        │
└──────────────────────────────────────────────────────┘
── Top Classes by Coupling
  1  CombatManager   23
  2  DataManager     18
── Circular Dependencies
  ↻ CombatCore → CombatUnit → CombatCore

3. Initialize AI Agent Context

# Creates .gdep/AGENTS.md — auto-read by Claude / Cursor / Gemini
gdep init {path}

---

🎯 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 trace (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
lint	Game-specific anti-pattern scan	Quality check before PR
graph	Dependency graph export	Documentation, visualization
diff	Dependency diff before/after git commit	PR review, CI gate
init	Create AI Agent context	First 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

---

🤝 AI Agent + MCP Integration

gdep provides an MCP server for direct use in Claude Desktop, Cursor, and other MCP-compatible AI agents.

Quick Install via npm (Recommended)

npm install -g gdep-mcp

Claude Desktop config (claude_desktop_config.json):

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

MCP Tools (30)

Tool	Scenario
get_project_context	Call first — full project overview
wiki_search	Call before any analysis — keyword search over previously analyzed classes/assets (FTS5 BM25). Instant if cached
wiki_list	List all wiki nodes with staleness status
wiki_get	Read full cached analysis 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	Safety check before modifying a class or method (method_name= for method-level callers)
trace_gameplay_flow	Trace how a feature works (C++→BP). summary=True for compact output
inspect_architectural_health	Full tech debt diagnosis
explore_class_semantics	Understand an unfamiliar class. Default compact=True keeps output AI-friendly; include_source=True appends source code
explain_method_logic	Internal control flow of a single method (Guard/Branch/Loop/Always). include_source=True appends method body
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= for only that method's body
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	Unity Inspector event bindings
analyze_unity_animator	Unity Animator state machine
analyze_ue5_gas	UE5 GAS system full analysis — confidence header + IS-A asset role breakdown
analyze_ue5_behavior_tree	UE5 BehaviorTree structure
analyze_ue5_state_tree	UE5 StateTree structure
analyze_ue5_animation	UE5 ABP + Montage analysis
analyze_ue5_blueprint_mapping	C++ class → Blueprint impl mapping — confidence header

---

🎮 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
Cocos2d-x (C++)	✅	✅	-	-
.NET (C#)	✅	✅	-	-
Generic C++	✅	✅	-	-

---

📋 Lint Rules

Rule ID	Engine	Description
UNI-PERF-001	Unity	GetComponent/Find in Update
UNI-PERF-002	Unity	new/Instantiate allocation in Update
UNI-ASYNC-001	Unity	Coroutine while(true) without yield
UNI-ASYNC-002	Unity	FindObjectOfType/Resources.Load inside 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 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 callback
UE5-BP-001	UE5	Blueprint references a C++ class not found in source
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

---

⚙️ C# Parser (gdep.dll)

The C# parser ships as an OS-agnostic single DLL, running identically on Windows · macOS · Linux.

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

---

📚 More

• Full README & Workflows
• MCP Server Setup
• CI/CD Integration
• Performance Benchmark