mobile-ai-agents 1.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/AGENTS.md +228 -0
  2. package/CLAUDE.md +236 -0
  3. package/LICENSE +21 -0
  4. package/README.md +652 -0
  5. package/agents/android/android-crash-analyzer/README.md +134 -0
  6. package/agents/android/android-crash-analyzer/agent.md +206 -0
  7. package/agents/android/android-crash-analyzer/example-input.md +138 -0
  8. package/agents/android/android-crash-analyzer/example-output.md +225 -0
  9. package/agents/android/anr-investigation/README.md +78 -0
  10. package/agents/android/anr-investigation/agent.md +117 -0
  11. package/agents/android/anr-investigation/example-input.md +62 -0
  12. package/agents/android/anr-investigation/example-output.md +103 -0
  13. package/agents/android/axiom/agent.md +197 -0
  14. package/agents/android/code-reviewer/README.md +108 -0
  15. package/agents/android/code-reviewer/agent.md +210 -0
  16. package/agents/android/code-reviewer/example-input.md +116 -0
  17. package/agents/android/code-reviewer/example-output.md +115 -0
  18. package/agents/android/compose-navigation/README.md +76 -0
  19. package/agents/android/compose-navigation/agent.md +121 -0
  20. package/agents/android/compose-navigation/example-input.md +49 -0
  21. package/agents/android/compose-navigation/example-output.md +325 -0
  22. package/agents/android/compose-screen-builder/README.md +95 -0
  23. package/agents/android/compose-screen-builder/agent.md +170 -0
  24. package/agents/android/compose-screen-builder/example-input.md +40 -0
  25. package/agents/android/compose-screen-builder/example-output.md +568 -0
  26. package/agents/android/compose-ui-reviewer/README.md +73 -0
  27. package/agents/android/compose-ui-reviewer/agent.md +253 -0
  28. package/agents/android/compose-ui-reviewer/example-input.md +84 -0
  29. package/agents/android/compose-ui-reviewer/example-output.md +102 -0
  30. package/agents/android/crash-analyzer/README.md +53 -0
  31. package/agents/android/crash-analyzer/agent.md +295 -0
  32. package/agents/android/memory-leak-analyzer/README.md +79 -0
  33. package/agents/android/memory-leak-analyzer/agent.md +116 -0
  34. package/agents/android/memory-leak-analyzer/example-input.md +78 -0
  35. package/agents/android/memory-leak-analyzer/example-output.md +128 -0
  36. package/agents/cross-platform/accessibility-auditor/README.md +47 -0
  37. package/agents/cross-platform/accessibility-auditor/agent.md +268 -0
  38. package/agents/cross-platform/accessibility-auditor/example-input.md +84 -0
  39. package/agents/cross-platform/accessibility-auditor/example-output.md +132 -0
  40. package/agents/cross-platform/appforge/agent.md +303 -0
  41. package/agents/cross-platform/ci-cd-generator/README.md +65 -0
  42. package/agents/cross-platform/ci-cd-generator/agent.md +422 -0
  43. package/agents/cross-platform/ci-cd-generator/example-input.md +69 -0
  44. package/agents/cross-platform/ci-cd-generator/example-output.md +261 -0
  45. package/agents/cross-platform/crasher/agent.md +221 -0
  46. package/agents/cross-platform/figma/agent.md +247 -0
  47. package/agents/cross-platform/launchpad/agent.md +330 -0
  48. package/agents/cross-platform/mobile-harness/agent.md +422 -0
  49. package/agents/cross-platform/mobile-memory/agent.md +429 -0
  50. package/agents/cross-platform/perf/agent.md +261 -0
  51. package/agents/cross-platform/pipeline/agent.md +288 -0
  52. package/agents/cross-platform/release-notes-generator/README.md +63 -0
  53. package/agents/cross-platform/release-notes-generator/agent.md +218 -0
  54. package/agents/cross-platform/release-notes-generator/example-input.md +71 -0
  55. package/agents/cross-platform/release-notes-generator/example-output.md +96 -0
  56. package/agents/cross-platform/scribe/agent.md +180 -0
  57. package/agents/cross-platform/security-scanner/README.md +61 -0
  58. package/agents/cross-platform/security-scanner/agent.md +287 -0
  59. package/agents/cross-platform/security-scanner/example-input.md +77 -0
  60. package/agents/cross-platform/security-scanner/example-output.md +141 -0
  61. package/agents/cross-platform/sentinel/agent.md +217 -0
  62. package/agents/cross-platform/store-listing-writer/README.md +58 -0
  63. package/agents/cross-platform/store-listing-writer/agent.md +380 -0
  64. package/agents/cross-platform/store-listing-writer/example-input.md +67 -0
  65. package/agents/cross-platform/store-listing-writer/example-output.md +131 -0
  66. package/agents/flutter/bloc-feature-builder/README.md +101 -0
  67. package/agents/flutter/bloc-feature-builder/agent.md +225 -0
  68. package/agents/flutter/bloc-feature-builder/example-input.md +47 -0
  69. package/agents/flutter/bloc-feature-builder/example-output.md +838 -0
  70. package/agents/flutter/dart/agent.md +223 -0
  71. package/agents/flutter/widget-generator/README.md +66 -0
  72. package/agents/flutter/widget-generator/agent.md +264 -0
  73. package/agents/flutter/widget-generator/example-input.md +71 -0
  74. package/agents/flutter/widget-generator/example-output.md +163 -0
  75. package/agents/gaming/forge/agent.md +197 -0
  76. package/agents/gaming/unreal/agent.md +200 -0
  77. package/agents/ios/crash-analyzer/README.md +69 -0
  78. package/agents/ios/crash-analyzer/agent.md +300 -0
  79. package/agents/ios/crash-analyzer/example-input.md +83 -0
  80. package/agents/ios/crash-analyzer/example-output.md +126 -0
  81. package/agents/ios/swift/agent.md +206 -0
  82. package/agents/ios/swift-reviewer/README.md +68 -0
  83. package/agents/ios/swift-reviewer/agent.md +231 -0
  84. package/agents/ios/swift-reviewer/example-input.md +100 -0
  85. package/agents/ios/swift-reviewer/example-output.md +127 -0
  86. package/agents/react-native/bridge/agent.md +212 -0
  87. package/agents/react-native/performance-optimizer/README.md +81 -0
  88. package/agents/react-native/performance-optimizer/agent.md +284 -0
  89. package/agents/react-native/performance-optimizer/example-input.md +104 -0
  90. package/agents/react-native/performance-optimizer/example-output.md +132 -0
  91. package/agents/unity/shader-generator/README.md +77 -0
  92. package/agents/unity/shader-generator/agent.md +270 -0
  93. package/agents/unity/shader-generator/example-input.md +70 -0
  94. package/agents/unity/shader-generator/example-output.md +160 -0
  95. package/agents/unreal/blueprint-advisor/README.md +71 -0
  96. package/agents/unreal/blueprint-advisor/agent.md +311 -0
  97. package/agents/unreal/blueprint-advisor/example-input.md +73 -0
  98. package/agents/unreal/blueprint-advisor/example-output.md +217 -0
  99. package/cli/index.js +1091 -0
  100. package/docs/agent-guide.md +138 -0
  101. package/docs/chatgpt-integration.md +219 -0
  102. package/docs/core-loops.md +143 -0
  103. package/docs/cursor-integration.md +143 -0
  104. package/docs/getting-started.md +132 -0
  105. package/docs/index.html +711 -0
  106. package/docs/installation.md +271 -0
  107. package/docs/mobile-harness.md +160 -0
  108. package/docs/mobile-mcp.md +172 -0
  109. package/docs/mobile-memory.md +349 -0
  110. package/docs/release-process.md +85 -0
  111. package/docs/releases/release-v1.0.0.md +165 -0
  112. package/docs/roadmap/github-issues.md +239 -0
  113. package/docs/skill-categories.md +125 -0
  114. package/docs/vscode-copilot-integration.md +104 -0
  115. package/docs/wiki.md +615 -0
  116. package/install.sh +507 -0
  117. package/mobile-karpathy.md +79 -0
  118. package/package.json +57 -0
  119. package/skills/android/README.md +31 -0
  120. package/skills/android/android-tdd.md +89 -0
  121. package/skills/android/anr-investigation.md +251 -0
  122. package/skills/android/code-review.md +98 -0
  123. package/skills/android/compose-migration.md +48 -0
  124. package/skills/android/compose-review.md +78 -0
  125. package/skills/android/kotlin-modernize.md +51 -0
  126. package/skills/android/memory-leak-investigation.md +256 -0
  127. package/skills/android/proguard-rules.md +48 -0
  128. package/skills/cross-platform/accessibility-audit.md +63 -0
  129. package/skills/cross-platform/api-versioning.md +59 -0
  130. package/skills/cross-platform/clean-code-audit.md +239 -0
  131. package/skills/cross-platform/crash-triage.md +53 -0
  132. package/skills/cross-platform/deeplink-debug.md +57 -0
  133. package/skills/cross-platform/feature-slice.md +48 -0
  134. package/skills/cross-platform/grill-mobile.md +64 -0
  135. package/skills/cross-platform/mobile-mcp-qa.md +193 -0
  136. package/skills/cross-platform/mobile-memory-graph.md +179 -0
  137. package/skills/cross-platform/mobile-memory-save.md +210 -0
  138. package/skills/cross-platform/mobile-memory-search.md +154 -0
  139. package/skills/cross-platform/perf-audit.md +61 -0
  140. package/skills/cross-platform/prd-verification.md +324 -0
  141. package/skills/cross-platform/release-prep.md +64 -0
  142. package/skills/cross-platform/security-audit.md +281 -0
  143. package/skills/cross-platform/store-listing.md +75 -0
  144. package/skills/flutter/README.md +32 -0
  145. package/skills/flutter/dart-modernize.md +47 -0
  146. package/skills/flutter/flutter-review.md +59 -0
  147. package/skills/flutter/flutter-tdd.md +73 -0
  148. package/skills/flutter/widget-extract.md +41 -0
  149. package/skills/flutter/widget-gen.md +131 -0
  150. package/skills/gaming/blueprint-to-cpp.md +51 -0
  151. package/skills/gaming/game-perf.md +54 -0
  152. package/skills/gaming/shader-gen.md +44 -0
  153. package/skills/gaming/unity-tdd.md +85 -0
  154. package/skills/ios/README.md +45 -0
  155. package/skills/ios/data-persistence.md +151 -0
  156. package/skills/ios/ios-tdd.md +90 -0
  157. package/skills/ios/networking.md +139 -0
  158. package/skills/ios/performance.md +122 -0
  159. package/skills/ios/swift-concurrency.md +57 -0
  160. package/skills/ios/swift-review.md +124 -0
  161. package/skills/ios/swiftui-review.md +49 -0
  162. package/skills/ios/swiftui-state.md +122 -0
  163. package/skills/ios/unit-testing.md +144 -0
  164. package/skills/ios/xcode-warnings.md +37 -0
  165. package/skills/react-native/README.md +42 -0
  166. package/skills/react-native/bridge-audit.md +104 -0
  167. package/skills/react-native/expo-optimize.md +55 -0
  168. package/skills/react-native/new-arch-migrate.md +53 -0
  169. package/skills/react-native/performance.md +124 -0
  170. package/skills/react-native/rn-review.md +53 -0
  171. package/skills/react-native/rn-tdd.md +76 -0
  172. package/skills/shared/README.md +46 -0
  173. package/skills/shared/accessibility-audit.md +132 -0
  174. package/skills/shared/crash-analysis.md +110 -0
  175. package/skills/shared/security-scan.md +149 -0
  176. package/skills/unity/README.md +31 -0
  177. package/skills/unity/shader-review.md +110 -0
  178. package/templates/agent-template.md +88 -0
  179. package/templates/prompt-template.md +50 -0
  180. package/templates/skill-template.md +64 -0
  181. package/templates/workflow-template.md +48 -0
  182. package/workflows/app-launch.md +66 -0
  183. package/workflows/appforge-workflow.md +232 -0
  184. package/workflows/ci-setup.md +77 -0
  185. package/workflows/crash-to-fix.md +71 -0
  186. package/workflows/feature-ship.md +61 -0
  187. package/workflows/game-level.md +72 -0
  188. package/workflows/mobile-harness.md +319 -0
  189. package/workflows/mobile-mcp-qa.md +228 -0
  190. package/workflows/mobile-memory-workflow.md +243 -0
  191. package/workflows/new-project-setup.md +93 -0
  192. package/workflows/new-screen.md +68 -0
  193. package/workflows/perf-sprint.md +78 -0
  194. package/workflows/release-cycle.md +71 -0
@@ -0,0 +1,160 @@
1
+ # Example Output — Unity Shader Generator
2
+
3
+ Full agent response to the input in [`example-input.md`](example-input.md).
4
+
5
+ ---
6
+
7
+ ```
8
+ SHADER: HolographicScanline
9
+ FILE: Shaders/HolographicScanline.shader
10
+ RENDER_PIPELINE: URP
11
+ MOBILE_FRIENDLY: Yes
12
+ ```
13
+
14
+ ```hlsl
15
+ Shader "Custom/HolographicScanline"
16
+ {
17
+ Properties
18
+ {
19
+ _MainTex ("Base Texture (optional)", 2D) = "white" {}
20
+ _TintColor ("Tint Color", Color) = (0.05, 0.15, 0.4, 0.75)
21
+ _ScanlineFreq ("Scanline Frequency", Range(10, 200)) = 60
22
+ _ScanlineSpeed ("Scanline Scroll Speed", Range(0, 5)) = 1.2
23
+ _ScanlineBright ("Scanline Brightness", Range(0, 1)) = 0.15
24
+ _EdgeGlow ("Edge Glow Intensity", Range(0, 2)) = 0.6
25
+ _EdgeFalloff ("Edge Glow Falloff", Range(1, 10)) = 3.0
26
+ }
27
+
28
+ SubShader
29
+ {
30
+ Tags
31
+ {
32
+ "RenderType" = "Transparent"
33
+ "Queue" = "Transparent"
34
+ "RenderPipeline" = "UniversalPipeline"
35
+ }
36
+
37
+ Blend SrcAlpha OneMinusSrcAlpha
38
+ ZWrite Off
39
+ Cull Back
40
+
41
+ Pass
42
+ {
43
+ Name "HolographicScanlinePass"
44
+
45
+ HLSLPROGRAM
46
+ #pragma vertex vert
47
+ #pragma fragment frag
48
+ #pragma prefer_hlslcc gles
49
+ #pragma exclude_renderers d3d11_9x
50
+
51
+ #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"
52
+
53
+ struct Attributes
54
+ {
55
+ float4 positionOS : POSITION;
56
+ float2 uv : TEXCOORD0;
57
+ };
58
+
59
+ struct Varyings
60
+ {
61
+ float4 positionHCS : SV_POSITION;
62
+ float2 uv : TEXCOORD0;
63
+ // Normalized object-space Y (0=bottom, 1=top) for edge glow calculation
64
+ float normalizedY : TEXCOORD1;
65
+ };
66
+
67
+ TEXTURE2D(_MainTex);
68
+ SAMPLER(sampler_MainTex);
69
+
70
+ CBUFFER_START(UnityPerMaterial)
71
+ float4 _MainTex_ST;
72
+ half4 _TintColor;
73
+ half _ScanlineFreq;
74
+ half _ScanlineSpeed;
75
+ half _ScanlineBright;
76
+ half _EdgeGlow;
77
+ half _EdgeFalloff;
78
+ CBUFFER_END
79
+
80
+ Varyings vert(Attributes IN)
81
+ {
82
+ Varyings OUT;
83
+ OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
84
+ OUT.uv = TRANSFORM_TEX(IN.uv, _MainTex);
85
+ // Remap object-space Y from [-0.5, 0.5] to [0, 1]
86
+ OUT.normalizedY = IN.positionOS.y + 0.5;
87
+ return OUT;
88
+ }
89
+
90
+ half4 frag(Varyings IN) : SV_Target
91
+ {
92
+ // Optional base texture — usually white/unused for pure color effects
93
+ half4 texColor = SAMPLE_TEXTURE2D(_MainTex, sampler_MainTex, IN.uv);
94
+
95
+ // Scrolling scanlines: sine wave over UV.y + time
96
+ // _Time.y = seconds since startup (no C# needed)
97
+ float scanlinePhase = IN.uv.y * _ScanlineFreq
98
+ - _Time.y * _ScanlineSpeed;
99
+ half scanline = sin(scanlinePhase * 3.14159) * 0.5h + 0.5h;
100
+ scanline = pow(scanline, 4.0h); // pow sharpens the line without branching
101
+ scanline *= _ScanlineBright;
102
+
103
+ // Edge glow: bright at y=0 and y=1, dark in the middle
104
+ // edgeMask = 0 at center, 1 at top/bottom edges
105
+ half edgeMask = 1.0h - abs(IN.normalizedY * 2.0h - 1.0h);
106
+ edgeMask = 1.0h - pow(edgeMask, _EdgeFalloff);
107
+ half edgeGlow = edgeMask * _EdgeGlow;
108
+
109
+ // Combine tint + scanline + edge glow + optional texture
110
+ half4 col = _TintColor;
111
+ col.rgb += scanline + edgeGlow;
112
+ col.rgb *= texColor.rgb;
113
+ col.a = _TintColor.a * texColor.a;
114
+
115
+ return col;
116
+ }
117
+ ENDHLSL
118
+ }
119
+ }
120
+ FallBack Off
121
+ }
122
+ ```
123
+
124
+ ---
125
+
126
+ **PROPERTIES REFERENCE:**
127
+
128
+ | Property | Type | Description |
129
+ |---|---|---|
130
+ | `_MainTex` | Texture2D | Optional base texture; leave white for pure color effect |
131
+ | `_TintColor` | Color (RGBA) | Base holographic tint; alpha controls overall transparency |
132
+ | `_ScanlineFreq` | Float (10–200) | Number of scanlines visible across the mesh height |
133
+ | `_ScanlineSpeed` | Float (0–5) | How fast scanlines scroll upward in units/second |
134
+ | `_ScanlineBright` | Float (0–1) | Brightness contribution of the scanline highlight |
135
+ | `_EdgeGlow` | Float (0–2) | Intensity of the top/bottom edge glow |
136
+ | `_EdgeFalloff` | Float (1–10) | How quickly the edge glow falls off toward the center |
137
+
138
+ ---
139
+
140
+ **MATERIAL SETUP:**
141
+
142
+ 1. In the Project window: right-click → Create → Material
143
+ 2. In the Inspector, set Shader to **Custom/HolographicScanline**
144
+ 3. Set `_TintColor` to (R:0.05, G:0.15, B:0.4, A:0.75) for the default blue holographic look
145
+ 4. Set `_ScanlineFreq` to 80, `_ScanlineSpeed` to 1.5
146
+ 5. Apply the material to a UI `RawImage` or a world-space `Quad` mesh
147
+ 6. For UI Canvas: ensure the Canvas Render Mode is "World Space" or use a `RawImage` on a Screen Space canvas
148
+
149
+ ---
150
+
151
+ **PERFORMANCE NOTES:**
152
+ - Instruction count: ~18 ALU, 1 texture sample — well within mobile budget
153
+ - No dynamic branching — `pow()` and `sin()` are hardware-optimized on modern mobile GPUs
154
+ - All `half` precision — safe on Mali/Adreno GPUs, reduces register pressure
155
+ - Recommended LOD: 100 (default)
156
+
157
+ **KNOWN LIMITATIONS:**
158
+ - Edge glow assumes the mesh pivot is centered (`positionOS.y` ranges ±0.5). For non-centered meshes, adjust `OUT.normalizedY = IN.positionOS.y + YOUR_OFFSET`
159
+ - Scanlines are UV-space — they stretch on non-square meshes. For screen-space scanlines, use a post-process pass instead
160
+ - No UI Stencil masking — add a Stencil block to the SubShader if this material needs to be masked by a UI mask
@@ -0,0 +1,71 @@
1
+ # Unreal Blueprint Advisor Agent
2
+
3
+ > Describe your Blueprint logic. Get a structured analysis of Tick usage, Cast chains, event-driven alternatives, C++ migration candidates, and the equivalent C++ code for high-priority items.
4
+
5
+ ---
6
+
7
+ ## What This Agent Does
8
+
9
+ Analyzes Unreal Engine Blueprint logic (from a text description or Blueprint-as-text export) and returns:
10
+
11
+ - **Tick audit** — what runs in Event Tick and whether it can be replaced with timers, delegates, or AI Perception
12
+ - **C++ migration candidates** — which Blueprint nodes are performance-critical and should move to C++, ranked HIGH/MEDIUM/LOW
13
+ - **C++ equivalent** — complete header + implementation for the highest-priority migration targets
14
+ - **Architecture assessment** — coupling, single-responsibility, component separation recommendations
15
+ - **Findings** — CRITICAL / WARNING / INFO per issue with a concrete Blueprint or C++ fix
16
+
17
+ ---
18
+
19
+ ## Files
20
+
21
+ | File | Purpose |
22
+ |---|---|
23
+ | [`agent.md`](agent.md) | Input format, output format, full system prompt |
24
+ | [`example-input.md`](example-input.md) | Enemy AI Blueprint with Tick-based chase logic |
25
+ | [`example-output.md`](example-output.md) | Full analysis with C++ migration code |
26
+
27
+ ---
28
+
29
+ ## Quick Start
30
+
31
+ ```
32
+ UE_VERSION: 5.4
33
+ INPUT_TYPE: description
34
+ ACTOR_CLASS: BP_EnemyCharacter extends ACharacter
35
+ DESCRIPTION:
36
+ [step-by-step description of the Blueprint event graph]
37
+ CONCERN: performance
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Input Types
43
+
44
+ | `INPUT_TYPE` | What to Provide |
45
+ |---|---|
46
+ | `description` | Step-by-step description of what each Blueprint node does |
47
+ | `blueprint-text` | Output from Blueprint Diff tool or "Blueprints as Text" export |
48
+ | `event-graph-summary` | Screenshot-derived summary of node connections |
49
+
50
+ ---
51
+
52
+ ## Output Preview
53
+
54
+ ```
55
+ [CRITICAL] GetPlayerCharacter + Cast in Event Tick
56
+ Problem : Cast To + GetPlayerCharacter called 60× per second per enemy.
57
+ With 20 enemies = 1,200 cast operations/second.
58
+ Fix : Cache in BeginPlay: CachedPlayer = Cast<APlayerCharacter>(GetPlayerCharacter())
59
+
60
+ [HIGH] MoveToActor called every Tick
61
+ Problem : Restarts the pathfinding request 60 times per second.
62
+ Fix : Call MoveToActor ONCE when chasing state begins; re-path only on OnMoveCompleted.
63
+ ```
64
+
65
+ ---
66
+
67
+ ## Related Agents
68
+
69
+ - [`agents/unity/shader-generator`](../../unity/shader-generator/) — Unity equivalent for GPU effects
70
+ - `prompts/game-dev/blueprint-to-cpp.md` — quick one-shot Blueprint → C++ conversion
71
+ - `prompts/game-dev/game-object-architecture.md` — component architecture design
@@ -0,0 +1,311 @@
1
+ # Agent 07 — Unreal Blueprint Advisor
2
+
3
+ **Platform:** Unreal Engine (Blueprints / C++)
4
+ **Category:** Game Development / Code Quality
5
+ **Complexity:** High
6
+
7
+ ---
8
+
9
+ ## Purpose
10
+
11
+ Analyzes an Unreal Engine Blueprint description or exported Blueprint JSON/text representation and provides concrete advice on: logic correctness, performance (tick usage, event-driven alternatives), Blueprint-to-C++ migration candidates, and architectural improvements. Produces an annotated analysis and, where applicable, the equivalent C++ code.
12
+
13
+ ---
14
+
15
+ ## Input Format
16
+
17
+ ```
18
+ UE_VERSION: <e.g. 5.4>
19
+ INPUT_TYPE: <description | blueprint-text | event-graph-summary>
20
+ ACTOR_CLASS: <e.g. BP_EnemyCharacter, BP_GameMode>
21
+ DESCRIPTION:
22
+ <Either:
23
+ (a) Plain-English description of what the Blueprint does, step by step.
24
+ (b) A text export or screenshot-derived summary of the Blueprint event graph.
25
+ (c) A Blueprints-as-text export from a tool like Blueprint Diff.>
26
+ CONCERN: <performance | correctness | migration | architecture | all>
27
+ ```
28
+
29
+ **Fields:**
30
+
31
+ | Field | Required | Description |
32
+ |---|---|---|
33
+ | `UE_VERSION` | Yes | Determines available APIs and nodes |
34
+ | `INPUT_TYPE` | Yes | How the Blueprint is described |
35
+ | `ACTOR_CLASS` | Yes | Base class or type being blueprinted |
36
+ | `DESCRIPTION` | Yes | Blueprint logic description |
37
+ | `CONCERN` | Yes | Focus area for the review |
38
+
39
+ ---
40
+
41
+ ## Output Format
42
+
43
+ ```
44
+ BLUEPRINT ANALYSIS
45
+ ==================
46
+ Actor Class : <class>
47
+ UE Version : <version>
48
+ Focus : <concern>
49
+
50
+ FINDINGS
51
+ --------
52
+ [CRITICAL] <Issue title>
53
+ Problem : <What is wrong and why it matters in production>
54
+ Fix : <Concrete change to make in Blueprint or equivalent C++ snippet>
55
+
56
+ [WARNING] <Issue title>
57
+ Problem : <What is wrong>
58
+ Fix : <Corrected approach>
59
+
60
+ [INFO] <Issue title>
61
+ Problem : <Suggestion>
62
+ Fix : <Improvement>
63
+
64
+ TICK AUDIT
65
+ ----------
66
+ Uses Tick: Yes / No
67
+ → <If Yes: what is inside Tick, and whether it can be replaced with
68
+ event-driven logic, timers, or delegates>
69
+
70
+ C++ MIGRATION CANDIDATES
71
+ ------------------------
72
+ | Node / Logic | Migration Priority | Reason |
73
+ |---|---|---|
74
+ | <blueprint node> | HIGH / MEDIUM / LOW | <why> |
75
+
76
+ C++ EQUIVALENT (for HIGH priority candidates)
77
+ ---------------------------------------------
78
+ ```cpp
79
+ <C++ code for the highest-priority migration target>
80
+ ```
81
+
82
+ ARCHITECTURE ASSESSMENT
83
+ -----------------------
84
+ <Overall assessment of the Blueprint's design: coupling, single-responsibility,
85
+ reusability, and whether it belongs in a Component, Actor, or GameMode.>
86
+
87
+ OVERALL VERDICT: <WELL STRUCTURED / NEEDS REFACTOR / MIGRATE TO C++>
88
+ ```
89
+
90
+ ---
91
+
92
+ ## System Prompt
93
+
94
+ ```
95
+ You are a senior Unreal Engine engineer with deep expertise in Blueprint scripting, C++ Gameplay Framework, performance optimization, and game architecture. Your job is to analyze a Blueprint Actor's logic (provided as a description or text representation) and produce structured, actionable advice.
96
+
97
+ For each finding:
98
+ - Assign severity: CRITICAL (incorrect behavior, crashes, or severe performance hit), WARNING (bad practice, scalability issue), INFO (style, minor improvement).
99
+ - State what is wrong and WHY it matters in a shipped game.
100
+ - Provide a concrete corrected Blueprint approach OR equivalent C++ code.
101
+
102
+ Key checks:
103
+ 1. Tick misuse: Is logic inside Event Tick that could be driven by events, delegates, or timers? Every unnecessary Tick eats frame budget.
104
+ 2. Cast chains: Are expensive `Cast To` nodes used in Tick or on overlapping events? Cast is relatively cheap once but expensive at high frequency.
105
+ 3. Blueprint-callable functions vs. macros: Are macros used where functions would be cleaner and more reusable?
106
+ 4. Event-driven design: Are game state changes driven by polling (checking variables in Tick) vs. broadcasting delegates/events?
107
+ 5. Interface usage: Are direct actor references used for cross-Blueprint communication where interfaces would decouple the logic?
108
+ 6. Component responsibility: Is logic in the Actor that belongs in a Component (health, inventory, movement customization)?
109
+ 7. Replication: Are variables marked for replication without `RepNotify` where state changes need to trigger client-side logic?
110
+ 8. Migration candidates: Flag logic that is performance-critical (collision, AI perception, math-heavy) and should be in C++.
111
+
112
+ Output MUST follow the exact format specified.
113
+ ```
114
+
115
+ ---
116
+
117
+ ## Example
118
+
119
+ ### Input
120
+
121
+ ```
122
+ UE_VERSION: 5.4
123
+ INPUT_TYPE: description
124
+ ACTOR_CLASS: BP_EnemyCharacter (extends ACharacter)
125
+ DESCRIPTION:
126
+ On Event Tick:
127
+ 1. Get Player Character (cast to BP_PlayerCharacter).
128
+ 2. Get distance from self to player.
129
+ 3. If distance < 800, set IsChasing = true and call MoveToActor(player).
130
+ 4. If distance >= 800, set IsChasing = false and call StopMovement.
131
+ 5. If IsChasing and distance < 150, call AttackPlayer function.
132
+
133
+ On Event BeginPlay:
134
+ - Set health to 100.
135
+ - Register overlap event on CapsuleComponent.
136
+
137
+ On CapsuleComponent Overlap (with BP_Projectile):
138
+ 1. Cast to BP_Projectile, get Damage value.
139
+ 2. Subtract Damage from Health.
140
+ 3. If Health <= 0, call Die function.
141
+
142
+ Die function:
143
+ - Play death animation.
144
+ - Destroy Actor after 3 seconds using SetTimer.
145
+ CONCERN: performance
146
+ ```
147
+
148
+ ### Output
149
+
150
+ ```
151
+ BLUEPRINT ANALYSIS
152
+ ==================
153
+ Actor Class : BP_EnemyCharacter (extends ACharacter)
154
+ UE Version : 5.4
155
+ Focus : Performance
156
+
157
+ FINDINGS
158
+ --------
159
+ [CRITICAL] GetPlayerCharacter + Cast in Event Tick
160
+ Problem : `Get Player Character` and `Cast To BP_PlayerCharacter` are called
161
+ every frame for every enemy. With 20 enemies at 60 FPS, that is
162
+ 1,200 cast operations per second. Cast is O(1) but generates
163
+ Blueprint overhead and forces a reference fetch from the world.
164
+ Fix : Cache the player reference in BeginPlay:
165
+ - In BeginPlay: Get Player Character → Cast to BP_PlayerCharacter
166
+ → Store in variable `CachedPlayer` (type: BP_PlayerCharacter).
167
+ - In Tick: use `CachedPlayer` directly, with a null check guard.
168
+
169
+ [CRITICAL] MoveToActor called every Tick
170
+ Problem : Calling `MoveToActor` every frame restarts the AI Move To request
171
+ each tick. This causes the AI controller to flush and re-issue its
172
+ pathfinding request 60 times per second, creating significant
173
+ NavMesh query overhead.
174
+ Fix : Replace with event-driven chasing:
175
+ - Use a Timer (every 0.2s) to check distance and toggle chasing state.
176
+ - Call MoveToActor only once when transitioning to chasing state
177
+ (IsChasing goes from false → true).
178
+ - Use AIController's OnMoveCompleted delegate to know when to re-path.
179
+
180
+ [WARNING] Distance check logic duplicated in Tick
181
+ Problem : The distance-to-player check runs three separate evaluations
182
+ per tick (chase enter, chase exit, attack range). This is redundant.
183
+ Fix : Compute distance once per timer tick, store in a local variable,
184
+ then branch on the single value for all three conditions.
185
+
186
+ [WARNING] Attack triggered in Tick (distance < 150)
187
+ Problem : AttackPlayer can be called every frame when the player is in range,
188
+ firing an attack 60 times per second unless internally gated.
189
+ Fix : Add a boolean `bIsAttacking` flag and set it to true when an attack
190
+ starts, false when the attack animation notifies completion.
191
+ Gate the attack call: `if !bIsAttacking → AttackPlayer → set bIsAttacking`.
192
+
193
+ [INFO] SetTimer by function name in Die
194
+ Problem : `SetTimer by Function Name` is Blueprint-legacy. It uses string-based
195
+ lookup which is slower and cannot be refactored safely.
196
+ Fix : Replace with `SetTimer by Event` and bind to a custom event node
197
+ called `OnDeathTimerExpired` that calls Destroy Actor.
198
+
199
+ TICK AUDIT
200
+ ----------
201
+ Uses Tick: Yes
202
+ → Tick contains: player reference fetch, distance calculation, MoveToActor,
203
+ and attack check — ALL of which can and should be moved out of Tick.
204
+ → Recommended: Disable Tick entirely on this Actor. Replace with:
205
+ - A 0.1–0.2s Timer for the chase/attack state machine.
206
+ - AI Perception Component (sight) as the trigger to begin chasing, rather
207
+ than distance polling. This scales to large enemy counts with no per-frame cost.
208
+
209
+ C++ MIGRATION CANDIDATES
210
+ ------------------------
211
+ | Node / Logic | Migration Priority | Reason |
212
+ |---|---|---|
213
+ | Distance check + state machine | HIGH | Called every frame on many actors |
214
+ | MoveToActor / pathfinding control | HIGH | NavMesh queries need C++ AIController |
215
+ | Health subtraction on overlap | MEDIUM | Simple math; Blueprint is acceptable |
216
+ | Death sequence + timer | LOW | Cosmetic; Blueprint is fine |
217
+
218
+ C++ EQUIVALENT (for HIGH priority candidates)
219
+ ---------------------------------------------
220
+ ```cpp
221
+ // AEnemyCharacter.h
222
+ UCLASS()
223
+ class AEnemyCharacter : public ACharacter
224
+ {
225
+ GENERATED_BODY()
226
+
227
+ public:
228
+ AEnemyCharacter();
229
+
230
+ protected:
231
+ virtual void BeginPlay() override;
232
+
233
+ UPROPERTY(EditAnywhere, Category = "AI")
234
+ float ChaseRadius = 800.f;
235
+
236
+ UPROPERTY(EditAnywhere, Category = "AI")
237
+ float AttackRadius = 150.f;
238
+
239
+ UPROPERTY(EditAnywhere, Category = "AI")
240
+ float StateUpdateInterval = 0.15f;
241
+
242
+ private:
243
+ UPROPERTY()
244
+ TObjectPtr<ACharacter> CachedPlayer;
245
+
246
+ FTimerHandle StateTimerHandle;
247
+ bool bIsChasing = false;
248
+ bool bIsAttacking = false;
249
+
250
+ void UpdateChaseState();
251
+ void OnAttackComplete(); // called by AnimNotify
252
+ };
253
+
254
+ // AEnemyCharacter.cpp
255
+ void AEnemyCharacter::BeginPlay()
256
+ {
257
+ Super::BeginPlay();
258
+ CachedPlayer = UGameplayStatics::GetPlayerCharacter(this, 0);
259
+ GetWorldTimerManager().SetTimer(
260
+ StateTimerHandle, this, &AEnemyCharacter::UpdateChaseState,
261
+ StateUpdateInterval, true);
262
+ }
263
+
264
+ void AEnemyCharacter::UpdateChaseState()
265
+ {
266
+ if (!CachedPlayer) return;
267
+ const float Dist = FVector::Dist(GetActorLocation(), CachedPlayer->GetActorLocation());
268
+
269
+ if (Dist < ChaseRadius)
270
+ {
271
+ if (!bIsChasing)
272
+ {
273
+ bIsChasing = true;
274
+ if (AAIController* AI = Cast<AAIController>(GetController()))
275
+ AI->MoveToActor(CachedPlayer);
276
+ }
277
+ if (Dist < AttackRadius && !bIsAttacking)
278
+ {
279
+ bIsAttacking = true;
280
+ // Trigger attack montage; OnAttackComplete() resets bIsAttacking
281
+ }
282
+ }
283
+ else if (bIsChasing)
284
+ {
285
+ bIsChasing = false;
286
+ if (AAIController* AI = Cast<AAIController>(GetController()))
287
+ AI->StopMovement();
288
+ }
289
+ }
290
+ ```
291
+
292
+ ARCHITECTURE ASSESSMENT
293
+ -----------------------
294
+ The current Blueprint mixes perception (finding the player), movement control,
295
+ combat logic, and health management in a single Actor class. For a shipped game:
296
+ - Extract health into a `UHealthComponent` — reusable across enemies and the player.
297
+ - Use AI Perception Component (UAISenseConfig_Sight) to replace distance polling.
298
+ - Consider a Behavior Tree + Blackboard for the chase/attack state machine —
299
+ this scales to complex enemy AI without multiplying Tick cost.
300
+
301
+ OVERALL VERDICT: MIGRATE TO C++ (performance-critical path) + REFACTOR ARCHITECTURE
302
+ ```
303
+
304
+ ---
305
+
306
+ ## Notes
307
+
308
+ - For INPUT_TYPE `blueprint-text`, the agent accepts exports from Blueprint Diff tools or copy-paste from Blueprints-as-Text in the UE editor.
309
+ - The agent cannot visualize node graphs from screenshots — describe the graph in text.
310
+ - C++ snippets use UE 5.x API conventions. Verify include paths for your specific UE version.
311
+ - Tested with: Claude Sonnet 4.6, GPT-4o.
@@ -0,0 +1,73 @@
1
+ # Example Input — Unreal Blueprint Advisor
2
+
3
+ ---
4
+
5
+ ```
6
+ UE_VERSION: 5.4
7
+ INPUT_TYPE: description
8
+ ACTOR_CLASS: BP_EnemyCharacter (extends ACharacter)
9
+ CONCERN: performance
10
+ DESCRIPTION:
11
+ On Event Tick:
12
+ 1. Get Player Character → Cast To BP_PlayerCharacter.
13
+ 2. Calculate distance from self to player (VectorLength of subtracted locations).
14
+ 3. If distance < 800, set IsChasing = true and call MoveToActor(player).
15
+ 4. If distance >= 800, set IsChasing = false and call StopMovement.
16
+ 5. If IsChasing is true AND distance < 150, call AttackPlayer custom function.
17
+
18
+ On Event BeginPlay:
19
+ - Set Health = 100.
20
+ - Register OnComponentBeginOverlap on CapsuleComponent.
21
+
22
+ On CapsuleComponent Overlap (with AnyActor):
23
+ 1. Cast to BP_Projectile, get Damage value.
24
+ 2. Subtract Damage from Health.
25
+ 3. If Health <= 0, call Die function.
26
+
27
+ Die (custom function):
28
+ - Play death montage.
29
+ - Set timer by function name "DestroySelf" with 3.0 second delay.
30
+ - DestroySelf calls DestroyActor.
31
+ ```
32
+
33
+ ---
34
+
35
+ ## What to Expect
36
+
37
+ The agent identifies five issues across two severity levels and produces C++ migration code for the two HIGH-priority items. See [`example-output.md`](example-output.md).
38
+
39
+ **Issue map:**
40
+ 1. `GetPlayerCharacter + Cast` in Event Tick — CRITICAL (1,200+ operations/second with 20 enemies)
41
+ 2. `MoveToActor` called every Tick — CRITICAL (restarts pathfinding 60× per second)
42
+ 3. Attack check in Tick — WARNING (needs a gate to prevent 60 attacks/second)
43
+ 4. `SetTimer by Function Name` — INFO (legacy string-based API, prefer SetTimer by Event)
44
+ 5. No component separation (health, damage, AI state all in root Actor) — WARNING
45
+
46
+ ---
47
+
48
+ ## Variations
49
+
50
+ ### Pickup Actor
51
+ ```
52
+ UE_VERSION: 5.4
53
+ INPUT_TYPE: description
54
+ ACTOR_CLASS: BP_Pickup extends AActor
55
+ CONCERN: architecture
56
+ DESCRIPTION:
57
+ On BeginPlay: set a rotating timer every 0.05 seconds that adds 2 degrees of Z rotation.
58
+ On ActorBeginOverlap with Pawn: Cast to BP_PlayerCharacter, call AddCoins(10),
59
+ play a SoundCue, destroy self after a SetTimer delay of 0.1 seconds.
60
+ ```
61
+
62
+ ### Vehicle controller
63
+ ```
64
+ UE_VERSION: 5.4
65
+ INPUT_TYPE: description
66
+ ACTOR_CLASS: BP_VehicleController extends AWheeledVehiclePawn
67
+ CONCERN: all
68
+ DESCRIPTION:
69
+ On Event Tick: read Axis input for throttle and steering using GetInputAxisValue.
70
+ Apply throttle with SetThrottleInput. Apply steering with SetSteeringInput.
71
+ If speed > 100, enable boost by increasing max engine torque.
72
+ Check if player is pressing Handbrake with IsInputKeyDown each tick.
73
+ ```