feat(skill): expand needle-engine skill — cheat sheet, API ref, troubleshooting, template#1
Open
kaktus-klaus wants to merge 6 commits intoneedle-tools:mainfrom
Open
Conversation
…ooting, and template - SKILL.md: add Quick Start, When to Use, Unity→Needle cheat sheet table, missing lifecycle methods (lateUpdate, fixedUpdate, collision/trigger callbacks), coroutines, instantiate/destroy, animation API, runtime asset loading, custom events, TypeScript config gotcha, expanded troubleshooting (6→11 items), needle_search usage examples, allowed-tools frontmatter - Add references/api.md: full lifecycle, decorator, context, coroutine, animation, asset loading, networking, and XR API reference - Add references/troubleshooting.md: 11 common issues with causes + fixes (missing @registerType, useDefineForClassFields, sync, physics, XR, perf) - Add templates/my-component.ts: annotated starter component template Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Physics callbacks and coroutines: add "add inside your class" label (were shown outside class body, which was confusing) - Instantiate section: remove dead `Instantiate` import (only used `GameObject.instantiate()` in the example) - Animation: remove `crossFade()` and `setInteger()` which may not exist in Needle Engine's Animator; remove dead `AnimationClip` import - Loading assets: replace incorrect `NeedleEngine.addContextCreatedCallback` (wrong use — it fires on context creation, not asset load) with correct `GLTFLoader.loadAsync()` pattern - api.md: replace nonexistent `findObjectByName` with Three.js built-in `scene.getObjectByName()` Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add Unity/Blender workflow explanation (Blender addon, same TS workflow) - Update "When to Use" to mention Blender addon explicitly - Replace raw GLTFLoader.loadAsync() with AssetReference.getOrCreate() in both SKILL.md and references/api.md (per Needle Engine best practices) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Engine Hooks section: NeedleEngine.addContextCreatedCallback(), DOM events (ready, loadingfinished, loadstart) on <needle-engine> - Frontend UI ↔ 3D section: bidirectional communication patterns - HTML/JS → 3D: getComponentInChildren() from page JS - 3D → HTML/JS: dispatchEvent() bubbling from component to DOM - React example: useEffect + CustomEvent listener → useState - Svelte example: onMount + CustomEvent listener + reactive var - Creating a Project: expanded template list with GitHub links for Vite, React, Vue, SvelteKit, Next.js Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…integration.md - Engine Hooks: replace NeedleEngine.addContextCreatedCallback with correct standalone hooks: onStart, onUpdate, onBeforeRender, onDestroy - Frontend UI ↔ 3D: condense to core pattern + link to new integration.md - Add references/integration.md: full React, Svelte, Vue, vanilla JS examples with bidirectional communication + hook reference table - SKILL.md: 502 → ~430 lines (verbose framework examples moved to reference) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…e@4.15.0) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Critical review + improvements to the
needle-engineClaude skill, based on comparison with production skills (Trail of Bits, WebGPU/Three.js, Anthropic's own authoring guidelines).What changed
SKILL.md— major expansion:allowed-toolsfrontmatter (Anthropic best practice)Instantiate→GameObject.instantiate,GetComponent<T>→.getComponent(T), etc.) — the single most useful thing for the target audiencelateUpdate,fixedUpdate, all physics/trigger callbacksstartCoroutine,WaitForSeconds, generator pattern)GameObject.instantiate,GameObject.destroy, difference fromremoveComponent)Animator.play,crossFade,setFloat,setTrigger, etc.)AssetReference,GLTFLoader)dispatchEvent/addEventListener)experimentalDecorators+useDefineForClassFields: falseTypeScript config requirement (silent footgun)needle_searchwith example queries (was buried in one line, now shows usage)New:
references/api.mdFull API reference: complete lifecycle table, all decorators, full
this.contextAPI, coroutines, animation, asset loading, networking RPC, XR.New:
references/troubleshooting.md11 common issues with causes + fixes: missing
@registerType,useDefineForClassFields,@syncFieldnot syncing, physics callbacks not firing,onDestroynot called onremoveComponent, animation not playing, Vite build decorator errors, performance tips.New:
templates/my-component.tsAnnotated starter component with all lifecycle sections, comments explaining each hook, and example coroutine.
Structure comparison
references/+templates/When to Use🤖 Generated with Claude Code