react-three-game
Build and edit React Three Game scenes using WebGPU rendering, React Three Fiber composition, prefab components and the editor API for agents.
How do I install this agent skill?
npx skills add https://github.com/prnthh/react-three-game-skill --skill react-three-gameIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a framework for building 3D games using React Three Fiber and JSON configurations. It defines a data-driven architecture for scene composition, asset loading, and runtime logic that follows standard software development practices.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
3/3 files flagged
What does this agent skill do?
React Three Game
React Three Game is a game creation toolbox for the web. A prefab is a JSON scene document: nodes describe objects, and components give them settings and behavior. Agents can work through the running editor, edit those documents directly, or add components in application source. Choose the path that fits the task and available files.
Choose how to work
| Task or context | Approach |
|---|---|
| Adjust a visible scene and inspect placement | Use the editor API |
| Change a saved scene, generate content, or review a file diff | Edit saved prefab JSON |
| Add reusable behavior, hooks, or a new rendering feature | Add custom components in source |
| Render JSON alongside the app's own canvas content | Embed PrefabRoot |
| Connect gameplay, physics, lighting, or loading | State and resources and Focused references |
These approaches can be combined: add a component in source, configure instances in JSON, then inspect them in the editor or viewer. Use the existing schemas and nearby application code to discover conventions.
Start with an inline prefab
Render a small, self-contained definition:
import { GameCanvas, PrefabRoot, type Prefab } from 'react-three-game/viewer';
const level: Prefab = {
root: { id: 'world', children: [{ id: 'box', components: {
geometry: { type: 'Geometry', properties: { geometryType: 'box' } },
material: { type: 'Material', properties: { color: '#ef806a' } },
} }] },
};
export default function App() {
return <div style={{ height: '100vh' }}>
<GameCanvas camera={{ position: [4, 3, 6] }}>
<ambientLight intensity={2} />
<PrefabRoot data={level} />
</GameCanvas>
</div>;
}
To edit the same level, render the editor, which includes its own canvas:
import { PrefabEditor } from 'react-three-game/editor';
<PrefabEditor prefab={level} />
Pack and duplicate an assembly for reuse inside the scene; save a separate prefab file when sharing across scenes or loading by URL. Keep module-level data stable between renders.
Edit a scene
Connect and find the object
Run JavaScript in the frame containing PrefabEditor:
const scene = window.scene;
scene.info(); // Check mode and how this scene can be saved.
const { node } = scene.find({ query: 'north wall' }); // Requires one match.
await scene.setMode({ mode: 'edit' });
scene.look({ id: node.id });
Inspect the target and its component schema:
scene.search({ query: 'wall', limit: 20 }); // Choose an ID when find is ambiguous.
scene.get({ id: node.id, resolved: true }); // Full properties and defaults.
scene.components({ names: ['Material'] }); // Supported settings for a type.
Component instance keys belong to the node and can differ from type names.
PrefabEditor exposes window.scene by default. Access it in the editor’s frame after mounting and reacquire it after navigation.
Make one change and inspect it
Writes require Edit mode. Start with a suitable existing object and preserve the scene's hierarchy and visual conventions.
await scene.setMode({ mode: 'edit' });
scene.update({ id: node.id, transform: { position: [2, 1, 0] } });
scene.look({ id: node.id });
// Wait for the updated objects and assets to mount.
const image = await scene.capture({ helpers: false });
Display image.dataUrl and inspect the result. Each update is one undo step.
await scene.setMode({ mode: 'play' }); // Check animation or physics.
// Observe the behavior before continuing.
await scene.setMode({ mode: 'edit' });
Use scene.undo() to reverse an authored edit or await scene.reset() to restore
live objects from the current document while keeping edits and history.
Reuse an assembly inline
After choosing the authored node above:
scene.pack({ id: node.id });
scene.duplicate({ id: node.id, newId: 'assembly-copy' });
scene.transform({ id: 'assembly-copy', position: [6, 1, 0] });
Packing marks the original node packed: true and keeps its components and
children in place. Copies use PrefabRef with {prefabId: "original-node-id"}
and independent transforms. Edit the original subtree to update copies.
Expand one copy with await scene.unpack({id:'assembly-copy'}) for independent
editing, then pack it to make a new reusable definition.
For reuse across scenes, export the portable definition:
const { prefab } = scene.exportPrefab({ id: 'assembly-copy' });
const json = JSON.stringify(prefab, null, 2);
Save json in public/prefabs, then use its served URL in a PrefabRef.
Scene saves include inline definitions automatically.
Save the result
if (scene.info().saveMethod === 'save') {
await scene.save(); // Host's onSaveScene callback.
} else {
const json = scene.exportJSON(); // Write this string to the scene's source file.
}
Write exported JSON to the chosen destination, then report the change and validation.
Find a more specific operation
scene.help() lists methods. Read the relevant section of Editor scene for agents for capture options, component edits, placement, downloads, packing, or atomic batches. In this checkout, use docs/public/editor-scene-for-agents.md.
Individual edits use the current revision automatically. Use expectedRevision when coordinating against a previous read; validate() and batch() require it. If a guarded write conflicts, reread and replan. Use batches to commit dependent edits together.
Render JSON in the app's canvas
Build on the inline level above to compose JSX, gameplay, and shared resources.
Import custom component registrations before mounting.
With an existing R3F Canvas
Add PrefabRoot to the app's existing WebGPU canvas:
import { Canvas } from '@react-three/fiber';
import { PrefabRoot } from 'react-three-game/viewer';
// level is the inline prefab above; canvasProps is the app's existing canvas setup.
<Canvas {...canvasProps}>
<PrefabRoot data={level} />
</Canvas>
Access the prefab from gameplay
Mount the app's gameplay component inside the prefab to access its document:
import { GameCanvas, PrefabRoot } from 'react-three-game/viewer';
<GameCanvas>
<PrefabRoot id="level" data={level}>
<Gameplay /> {/* Can use usePrefabDocument() for authored edits. */}
</PrefabRoot>
<PrefabRoot id="props" data={propsPrefab} />
</GameCanvas>
GameCanvas supplies shared runtime services. PrefabRoot supplies its document
context and creates runtime services when needed. With a custom canvas, wrap
sibling prefab roots in SceneRuntime to share events, assets, and component queries.
For sound in a custom canvas, wrap its content in BrowserRuntime; GameCanvas
already supplies it.
Node behavior uses component Views; the host supplies gameplay state and timing.
Prefab conventions
IDs are unique within a prefab. Component instance keys belong to the node;
type selects a registered component. Add a transform to the inline box from
the first example:
level.root.children![0].components!.transform = {
type: 'Transform', properties: {
position: [0, 1, 0], rotation: [0, 0.3, 0], scale: [2, 1, 1],
},
};
Run this while defining the document, before mounting. Y is up, rotations are XYZ Euler radians, and parent transforms also affect children and colliders.
Common asset entries under components:
{
// Model assets use their embedded materials.
"model": { "type": "Model", "properties": { "filename": "/models/tree.glb" } },
// For primitive meshes: texture is the color map, normalMapTexture the normal map.
"surface": { "type": "Material", "properties": { "texture": "/textures/stone.jpg" } },
// Reference a shared assembly by its served URL.
"building": { "type": "PrefabRef", "properties": { "url": "/prefabs/building.json" } }
}
Use known asset URLs; remote assets need CORS. Validate loading in the browser.
The viewer entrypoint registers built-in components, including Terrain, BoneAttachment, PostProcessing, and ClusteredLighting.
Root-scoped components (RenderSettings, PostProcessing, ClusteredLighting, ChunkSettings) belong on the document root. Nested prefab copies inherit the
outer scene configuration. Render settings inherit Three.js/host defaults.
Keep one active Camera and Fog per scene. Edit mode uses editor camera controls.
Edit saved prefab JSON
Find the file the app loads through an import or prefab URL, then edit it directly. Preserve node IDs, component keys, and unrelated fields. Check JSON syntax, unique IDs, component schemas, and registration. Reload the editor/viewer from the changed file before continuing API edits, and inspect the result and diff.
Custom components
Use application source for reusable behavior, React hooks, and new visual components.
Component data
name and properties define editable data. Add a View when behavior is needed.
import { registerComponent, type Component } from 'react-three-game/viewer';
const Health: Component<{ max: number }> = {
name: 'Health',
properties: { max: { default: 100 } },
};
registerComponent(Health);
Settings with behavior
Add a View to use React hooks and the live node object. Return children to preserve subsequent components and authored child nodes.
import { useFrame } from '@react-three/fiber';
import { registerComponent, useComponentActive, useGameObject,
type Component, type ComponentViewProps } from 'react-three-game/viewer';
type SpinProps = { speed: number };
function SpinView({ properties, enabled, children }: ComponentViewProps<SpinProps>) {
const object = useGameObject();
const active = useComponentActive(enabled);
// Animate the live object; document writes are for authored edits.
useFrame((_, delta) => {
if (active && object.transform) {
object.transform.rotation.y += properties.speed * delta;
}
});
return <>{children}</>;
}
const Spin: Component<SpinProps> = {
name: 'Spin', View: SpinView,
// Defaults feed both the view and the generated inspector.
properties: { speed: { default: 1, step: 0.1 } },
};
registerComponent(Spin);
Attach to a node
Import the registration module before mounting the editor or viewer, then add an
entry under the node's components. The instance key is local to the node;
type matches the registered name.
{
"spin": { "type": "Spin", "properties": { "speed": 2 } }
}
Property and rendering contracts
Fields inside a component definition:
properties: {
speed: { default: 1 }, // Numbers infer their type.
label: { type: 'string', default: 'Box' }, // Other values specify a type.
mode: {
type: 'select', default: 'walk',
options: [{ value: 'walk', label: 'Walk' }, { value: 'run', label: 'Run' }],
},
},
slot: 'geometry', // Render role: 'geometry', 'object', or 'material'.
exclusive: 'geometry', // Allows one component in this group per node.
category: 'mesh', // Editor grouping.
Views receive resolved defaults, and property schemas generate inspector controls.
Use scope: 'scene' for configuration on the outer document root. Geometry views
compose their mesh and geometry; material views attach inside them. Preserve
children when composing views. Gate Play-mode behavior with useComponentActive(enabled)
and return cleanup from effects.
Register a custom inspector in the editor entrypoint:
import { registerComponentEditor } from 'react-three-game/editor';
registerComponentEditor(Spin, SpinInspector); // App-defined component and inspector.
State and resources
| Need | Use |
|---|---|
| Current node object and runtime handles | useGameObject() |
| Node/edit state | useNode() |
| Authored document and serializable edits | usePrefabDocument() |
| Prefab-local object lookup and asset base path | usePrefab() |
| Shared model, texture and audio resources | useAssetRuntime() |
| Shared scene/mode | useScene() |
| View animation | Refs/live Three objects in R3F useFrame |
| Gameplay simulation | Host-owned state and tick loop |
| URL-backed prefab | PrefabInstance |
Load a prefab
Inside the canvas, load and prepare a prefab with PrefabInstance:
import { PrefabInstance } from 'react-three-game/viewer';
<PrefabInstance id="courtyard" url="/prefabs/courtyard.json" />
The instance prepares assets and shaders before activation. Unmounting releases
instance-owned objects; assets are shared. For distance-based streaming, configure
ChunkSettings on the scene root and mark spatial placements static.
Modify geometry
import { registerComponent, type Component } from 'react-three-game/viewer';
const Stretch: Component<{ amount: number }> = {
name: 'Stretch',
properties: { amount: { default: 1 } },
modifyGeometry: (source, { amount }) => source.clone().scale(1, amount, 1),
};
registerComponent(Stretch);
Return an owned clone of the source geometry. Modifiers run in component
order. The optional third argument supplies node scale as context.scale.
Material names resolve within each prefab document. Matching resolved settings can share GPU materials across documents.
Declare assets and share materials
In an asset-backed component definition, declare each resource used by its view:
dependencies: ({ filename }) => [{ kind: 'model', path: filename }],
Kinds are model, texture, sound, and prefab; paths respect basePath.
For imperative loading, useAssetRuntime() provides loadModel(path),
loadTexture(path), and loadSound(path), each returning the loaded resource.
Register parsed or generated resources with registerModel, registerTexture,
or registerSound.
Custom shared materials use useSharedMaterialResource and remain immutable.
Focused references
Choose a reference for the task:
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/prnthh/react-three-game-skill/react-three-game">View react-three-game on skillZs</a>