Skip to content

USER_GUIDE.md

Latest commit

 

History

History
351 lines (256 loc) · 11.9 KB

USER_GUIDE.md

File metadata and controls

351 lines (256 loc) · 11.9 KB
Raw

threejs-sculpt-dna — A GitHub Copilot Plugin: User Guide

1. Install from the canonical repository

Choose one installation source. Current Copilot CLI releases install a plugin directly from a GitHub repository:

copilot plugin install hyeonsangjeon/threejs-sculpt-dna

Verify the installation:

copilot plugin list

The repository also contains a decentralized marketplace manifest. Teams that need a registered catalog may use this alternative after removing any direct copy:

copilot plugin marketplace add hyeonsangjeon/threejs-sculpt-dna
copilot plugin marketplace browse threejs-copilot-plugins
copilot plugin install threejs-sculpt-dna@threejs-copilot-plugins

Do not keep direct, marketplace, and local copies active together. They can shadow one another and make updates appear stale.

Start a new Copilot session and check the available skills:

/skills list

You should see:

  • object-to-threejs-procedural
  • sculpt-dna-variants

GitHub Copilot plugin marketplaces are decentralized Git repositories. The file .github/plugin/marketplace.json registers this repository as the threejs-copilot-plugins marketplace without making that two-step path a requirement for direct installation.

If you cloned the repository, run the complete offline release proof:

python3 scripts/prove.py

PROOF PASS: 6/6 checks passed means executable policy, capability contract, first-clone health, Python compilation/contracts, and release evidence all pass. The runner never accesses the network and writes nothing unless --output explicitly names a proof JSON file. Run python3 scripts/doctor.py separately when diagnosing optional runtime gaps or duplicate Copilot installations.

Optional React Three Fiber runtime

The plugin's generated plain Three.js factory remains the runtime source of truth. React projects can mount that factory with the optional adapter:

import { SculptDNAAsset } from '@threejs-sculpt-dna/react-three-fiber';

<SculptDNAAsset
  factory={createModel}
  seed={20260712}
  variant="family-v001"
  onReady={(asset) => console.log(asset.runtime.sockets, asset.stats)}
/>

Copy adapters/react-three-fiber into a workspace package or consume it by a local package reference. Its only runtime requirements are peer dependencies: React 18/19, React Three Fiber 8/9, and Three.js. See the live adapter demo and examples/react-three-fiber for a complete Vite integration.

2. Attach a reference image

In GitHub Copilot:

  1. Open the project where the Three.js output should be created.
  2. Attach or drag an object reference image into the prompt.
  3. Describe the intended use: browser prop, hero render, game object, articulated asset, or destructible object.
  4. Ask Copilot to use the installed skills.

GitHub Copilot prompt with a Repolis Tree reference

3. Recommended prompts

Build one procedural object

Use Three.js Sculpt DNA for GitHub Copilot.

Reconstruct the object in this attached image as a browser-real-time,
action-ready procedural Three.js model.

Follow the locked workflow:
reference validation -> complexity assessment -> ObjectSculptSpec ->
blockout -> structure -> form -> materials -> surface details ->
browser screenshots and AI-vision correction.

Keep stable pivots, sockets, colliders, and destruction groups.
Do not use an imported mesh.

Generate a representative variant family

Use this only after the base sculpt has completed through surface-pass:

Use sculpt-dna-variants on the completed ObjectSculptSpec.

Define bounded semantic controls, preserve all topology and action-ready
invariants, generate 24 safe deterministic candidates, and use Coverage
Curator to select 3 broadly separated variants.

Render every selected variant from the same camera and keep each one blocked
until it receives fresh visual review.

Early design preview

Create a non-promotable Sculpt DNA preview family from this strict spec.
Mark it as preview mode, list the missing base passes, and do not describe
the variants as production-ready.

Flagship-quality result

Choose the strongest curated variant and art-direct it as the flagship.

Increase object-specific curve geometry, hierarchy depth, generated PBR,
instanced detail, lighting, camera, interaction, and optimization quality.
Capture pass-by-pass evidence and save the reusable production factory
separately from the demo page.

Verify the flagship inside a host app

After optimization, create a Render Integration Contract v1 for this asset.
Capture JSON snapshots from both the accepted standalone scene and the real
host app using the same fixed named cameras.

Gate tone mapping, output color space/pass count, exposure, DPR and render
targets, selective layers/lights, town spill, semantic coverage/luminance,
black/clipped frames, town exposure, calls/triangles/frame time/FPS, and
console/network errors. Do not treat diagnostic metrics as AI visual approval.

4. What Copilot should do

The installed workflow should:

  1. Reject or qualify unsuitable references.
  2. Estimate complexity before implementation.
  3. Decompose silhouette, structural components, materials, and surface details.
  4. Build in locked passes instead of jumping directly to a polished mesh.
  5. Compare browser renders with the reference and self-correct.
  6. Preserve pivots, sockets, colliders, hierarchy, and destruction metadata.
  7. Reset review evidence whenever a variant changes visible geometry or materials.
  8. Use Coverage Curator for representative families instead of taking the first random samples.
  9. Verify optimized host/app targets against standalone behavior before production acceptance.

Review history uses the latest entry for each pass as authoritative, so a stale superseded review cannot override a newer decision. Specs without reviewPolicy retain legacy local-path checks. Upgrade them to policy v2 with python3 scripts/migrate_review_policy.py object-sculpt-spec.json --in-place. Policy-v2 production reviews require local render and comparison files; all gates recompute their SHA-256 digests, and changed pixels invalidate completion. Remote or virtual evidence remains record-only.

Promoted families can add the manifest-only visualRegressionMatrix v1 block to define fixed viewpoints, pass bindings, expected render/comparison paths, and selected semantic targets. This is additive: no ObjectSculptSpec field is changed. The matrix verifies current reviews but does not render images or replace AI vision.

Host/app targets use separate additive render-integration-contract and render-runtime-snapshot v1 documents. They do not add fields to ObjectSculptSpec or existing reviews. The host gate compares exact renderer state and explicit tolerances/budgets; it has no wildcard ignore list. A standalone rotating camera can hide a fixed host-camera, layer, or occlusion bug, so capture every required named view in both environments.

5. Useful commands

Validate a spec:

python3 scripts/validate_sculpt_spec.py object-sculpt-spec.json --strict-quality

Check the active sculpt pass:

python3 scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json

Generate production variants after the evidence-backed base gate:

python3 scripts/sculpt_dna.py curate object-sculpt-spec.json \
  --out-dir variants \
  --count 3 \
  --pool-size 24 \
  --seed 1337

Generate an explicitly non-promotable preview:

python3 scripts/sculpt_dna.py curate object-sculpt-spec.json \
  --out-dir preview-variants \
  --count 3 \
  --pool-size 24 \
  --seed 1337 \
  --preview

Verify every required viewpoint for the base and promoted family:

python3 scripts/visual_regression_matrix.py \
  object-sculpt-spec.json \
  variants/sculpt-dna-manifest.json \
  --out variants/visual-regression-report.json \
  --summary

Without a manifest block, pass one or more --viewpoint VIEWPOINT_ID=PASS_ID options. Exit 0 means every cell passes; exit 1 means the deterministic report contains missing, stale, or failing cells; exit 2 means the inputs are invalid. JSON remains on stdout or in --out, while --summary writes human-readable output to stderr. See the matrix schema and migration note.

Verify an optimized model inside its host app:

python3 scripts/render_integration_contract.py \
  render-integration-contract.json \
  standalone-snapshot.json \
  host-snapshot.json \
  --out integration-report.json \
  --summary

Exit 0 means all required integration checks pass. Exit 1 means the valid report contains missing, stale, or failing checks. Exit 2 means malformed, unsafe, non-finite, unsupported-schema, or identity-inconsistent input. Coverage and luminance remain diagnostic only; AI vision is final authority. See the full contract, snapshot, report, and browser probe guide.

6. Update or uninstall

Update:

copilot plugin update threejs-sculpt-dna

Uninstall:

copilot plugin uninstall threejs-sculpt-dna

Remove the marketplace:

copilot plugin marketplace remove threejs-copilot-plugins

Use --force only when you also want to uninstall plugins installed from that marketplace.

7. Troubleshooting

Multiple copies or stale skills appear

Run:

copilot plugin list
python3 scripts/doctor.py

Keep exactly one threejs-sculpt-dna installation, preferably the direct hyeonsangjeon/threejs-sculpt-dna source, remove the other copy, and start a new Copilot session. Do not use --force until you have identified which marketplace owns any catalog-installed copy you intend to remove.

Marketplace is already registered from another source

copilot plugin marketplace remove threejs-copilot-plugins --force
copilot plugin marketplace add \
  hyeonsangjeon/threejs-sculpt-dna

Then reinstall the plugin.

Skills do not appear

Start a new Copilot session after installation and run /skills list.

Production variant generation is blocked

This is intentional. Complete evidence-backed reviews through surface-pass, ensure the screenshot and comparison files still exist, then sync the pipeline:

python3 scripts/sculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place

The visual regression matrix exits 1

Inspect each non-passing cell. Capture missing named viewpoints, restore or re-review stale SHA/path/camera bindings, and fix failed global, layer, or semantic AI-vision scores. Pixel metrics may help diagnose a mismatch but cannot approve the cell.

The host integration contract exits 1

Inspect checks in stable report order. tone-mapping-count usually means a host composer added a second OutputPass; town-light-spill means a hero-owned light reaches the town layer or exceeds its contribution limit; and view-coverage usually points to the fixed camera, clipping, layer masks, or an oversized occlusion proxy. Recapture both snapshots after fixing the host.

If the contract exits 2, fix the JSON/schema/path/SHA/identity error first. Do not convert it to an allowed difference. Host-specific differences must fit an explicit contract value, range, delta, or budget.

The reference is a crowded scene

Select one target object or explicitly accept a layered scene approximation. Do not claim exact hidden geometry from one image.

Official documentation