Skip to content
Back to search

terracotta-courtyard-3d

Build a cozy, desktop-first 3D miniature diorama with React 18, TypeScript, Three.js/R3F, procedural canvas textures, warm studio lighting, post-processing, and a catalog of 12 beveled/lathe-turned animated 1x1 courtyard props with zero external assets. Use when asked for a terracotta courtyard, procedural miniature/prop library, R3F diorama lighting study, or a Phase 1→2 3D web build with docs, QA, GitHub release and state file.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yx0128--terracotta-courtyard-3d-skill/badge.svg)](/listings/yx0128--terracotta-courtyard-3d-skill)

HTML

<a href="/listings/yx0128--terracotta-courtyard-3d-skill"><img src="/api/listings/yx0128--terracotta-courtyard-3d-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 168 lines
  1. ---
  2. name: terracotta-courtyard-3d
  3. description: Build a cozy, desktop-first 3D miniature diorama with React 18, TypeScript, Three.js/R3F, procedural canvas textures, warm studio lighting, post-processing, and a catalog of 12 beveled/lathe-turned animated 1x1 courtyard props with zero external assets. Use when asked for a terracotta courtyard, procedural miniature/prop library, R3F diorama lighting study, or a Phase 1→2 3D web build with docs, QA, GitHub release and state file.
  4. ---
  5. # Terracotta Courtyard 3D
  6. A field-tested playbook for building the **Terracotta Courtyard** app: a warm,
  7. floating miniature diorama built entirely from code, plus twelve modular
  8. miniatures — and the release engineering around it.
  9. Reference implementation: https://github.com/yx0128/terracotta-courtyard-3d
  10. ## What this skill produces
  11. 1. Vite + React 18 + TypeScript + Tailwind app.
  12. 2. **Phase 1** studio: cream backdrop + fog, warm sun, hemisphere fill,
  13. procedural Lightformer environment, contact shadows, N8AO + Bloom + ACES,
  14. damped orbit camera, drifting leaves, and a floating 3×3 beveled terracotta
  15. patch (`?view=study`).
  16. 3. **Phase 2** library: 12 procedural `1×1` items (structure, water, flora/life)
  17. with foam, ripples, koi, a pouring spout, candle flame and a hopping bird,
  18. arranged on a curated 4×3 showcase grid.
  19. 4. Cached, seeded canvas textures: terracotta grain + bump, water foam, foliage.
  20. 5. Pure metadata + component registry, tests, strict TS, lint, CI.
  21. 6. Professional docs: README, AGENTS, architecture, art direction, catalog, QA,
  22. reproduction, ADRs, contribution/security/conduct, release state file.
  23. 7. Verified GitHub release + a separately published skill backup repo.
  24. ## Use when
  25. - The user asks for a cozy 3D miniature courtyard, diorama, or prop library.
  26. - The user wants a procedural R3F lighting/material study with no external art.
  27. - The user wants a complete Phase 1→2 web build with docs and release steps.
  28. - Do **not** use for a generic dashboard, a Phaser/2D game, or work that allows
  29. GLB/HDR assets as the primary art pipeline.
  30. ## Non-negotiables
  31. - **Zero external assets.** No GLB/GLTF/HDR/images/audio/fonts/CDNs. Paint
  32. textures in `<canvas>`; build geometry with Three.js, `RoundedBoxGeometry`,
  33. `SplineCurve`+`LatheGeometry`, `TubeGeometry`, custom buffers.
  34. - **Pin React 18 + R3F 8 + drei 9 + @react-three/postprocessing 2.** R3F 9 /
  35. postprocessing 3 require React 19.
  36. - Every prop fits `1×1`, base at `y=0`, height ≈ 0.35–1.3.
  37. - Bevels everywhere: `radius ≈ 0.04` (clamp for thin parts). No bare sharp boxes
  38. or cones as finished props.
  39. - Palette: warm cream `#F3ECE0`, terracotta, limestone, olive, teal, brass,
  40. charcoal. No neon, pure white or pure black.
  41. - Deterministic art: seeded `mulberry32`; never `Math.random()` in textures,
  42. layout or animation.
  43. - Desktop-first; overlays `pointer-events-none` except links.
  44. ## Workflow
  45. ### 1. Protect credentials and confirm environment
  46. ```bash
  47. node --version && npm --version
  48. gh auth status # once
  49. ```
  50. At release time read the token once: `export GH_TOKEN="$(gh auth token)"`.
  51. Never repeat Keychain reads; push via `GIT_ASKPASS` (recipe in references).
  52. ### 2. Scaffold and pin dependencies
  53. Create `src/{components/items,data,lib,theme,utils}`, `docs`, `.github`,
  54. `skill/<name>/references`. Use Vite/TS/Tailwind/ESLint/Vitest configs from the
  55. reference repo. Install with `npm install --no-audit --no-fund`; approve
  56. esbuild's install script if npm blocks it.
  57. ### 3. Build pure foundations first
  58. `palette.ts` → `random.ts` (mulberry32/randRange/hashSeed) → `terraceLayout.ts`
  59. (tile 0.94, gap 0.06, pitch 1.0, centred slots) → tests.
  60. ### 4. Procedural textures
  61. Terracotta 256² colour + grayscale bump (radial clay base, mottling, ~3,600
  62. mineral specks, worn edges). Water foam 256² transparent wobbled rings. Foliage
  63. 128² olive dapple. Cache as lazy singletons; SRGB for colour, NoColorSpace for
  64. bump. **Keep UVs upright** — per-tile rotation of a RepeatWrapping map on a
  65. two-triangle face creates diagonal X seams.
  66. ### 5. Studio scene
  67. `<Canvas shadows flat ...>`, cream background + fog, sun 2.2 @ [12,18,10] with
  68. 2048² ±10 PCF soft shadows, hemisphere 0.85, `<Environment resolution=256
  69. frames={1}>` with warm Lightformers and `scene.environmentIntensity = 0.35`,
  70. `ContactShadows` frames=1, damped orbit, 8–10 drifting leaves. Composer:
  71. N8AO(0.6, 1.8, 0.8) → Bloom(1.05, 0.4, mipmap) → ACES ToneMapping. `<Canvas
  72. flat>` means tone mapping happens **once**. Exposure ≈ 0.96.
  73. ### 6. 3×3 study
  74. Nine `RoundedBoxGeometry(0.94, 0.18, 0.94, 4, 0.04)` pavers, pitch 1, shared
  75. cached maps, tint + sub-degree mesh rotation. Add a DOM HUD with texture swatches
  76. and click-through. This is the inspection view.
  77. ### 7. Item helpers and catalog
  78. `BeveledBox` (clamp radius; omit `args`/`children` from `MeshProps` before adding
  79. your args, or `position` becomes `never`), `Lathe` (SplineCurve profile), water
  80. material, expanding-ring effect, reusable songbird. Split geometry hooks into
  81. their own file for Fast Refresh/lint.
  82. Twelve items, exact costs: brick tile 10, limestone 10, stair 15, balustrade 25,
  83. birdbath 45, koi basin 50, spout 55, hedge 20, roses 25, column 30,
  84. candle+cushion 20, bench+bird 30 (total 335). Metadata in pure specs; components
  85. in a registry; 4×3 showcase with tinted pads. See references for part breakdown.
  86. ### 8. Verify
  87. ```bash
  88. npm run typecheck && npm run lint && npm test && npm run build
  89. ```
  90. Then headless Chrome 1440×900 for `/` and `/?view=study`; assert no console
  91. errors, all items visible, animations differ between frames. Full script in
  92. references.
  93. ### 9. Docs and state
  94. README (hero screenshot, views, catalog, controls, architecture, credits),
  95. AGENTS.md, architecture, art direction, catalog, QA, reproduction, ADRs,
  96. contribution/conduct/security/changelog/license, CI + templates, STATE.md with
  97. session id, model, cost, all five token columns, wall-clock time, exact SQL and
  98. the caveat that the snapshot excludes the final reply. Credit OpenCode and the
  99. model.
  100. ### 10. Publish safely
  101. One `GH_TOKEN` read, `gh repo create ... --public`, then push with
  102. `GIT_TERMINAL_PROMPT=0 git -c credential.helper= push` and a temporary
  103. `GIT_ASKPASS` script. Never put the token in the remote URL or repo. Publish the
  104. skill folder as its own repo with the same flow, then install copies into
  105. `~/.claude/skills/` and `~/.config/opencode/skills/`.
  106. ## Traps that cost time
  107. | Symptom | Fix |
  108. | --- | --- |
  109. | Diagonal X on every paver | Do not rotate/offset shared UV maps per tile; vary tint/mesh rotation |
  110. | Washed double-toned clay | `<Canvas flat>` + single composer ToneMapping |
  111. | React 19 peer errors | Stay on React 18 / R3F 8 / drei 9 / postprocessing 2 |
  112. | `position` typed `never` in helper | Omit `args`/`children` from `MeshProps` before extending |
  113. | Stale QA screenshots | Failed `tsc -b` hidden by `tail`; check build exit code |
  114. | Spout arc invisible | Start the Bézier outside the frog mouth; use a dark teal core + foam sleeve |
  115. | Catch-basin water hidden | Place water above the lathe surface, not inside the solid profile |
  116. | Keychain prompt loop | One `gh auth token`; `GIT_ASKPASS` for every push |
  117. ## Reference files
  118. - [references/build-playbook.md](references/build-playbook.md) — full Phase 1/2
  119. implementation recipe with dimensions, profiles and camera setups.
  120. - [references/art-and-lighting.md](references/art-and-lighting.md) — palette,
  121. lighting rig, material and motion rules.
  122. - [references/catalog.md](references/catalog.md) — exact item parts, dimensions
  123. and animations.
  124. - [references/release-checklist.md](references/release-checklist.md) — gates,
  125. screenshot QA, GitHub/askpass, state SQL, skill publication.
  126. ## Definition of done
  127. A stranger can clone the repo, run `npm ci && npm run dev`, switch between the
  128. study and showcase views, understand every item and animation, verify the build
  129. and reproduce the release — without asking you anything.
README.md · README · 18 lines
  1. # Terracotta Courtyard 3D — agent skill
  2. A reusable playbook for building a cozy procedural 3D miniature courtyard with
  3. React 18, TypeScript, Three.js/R3F, canvas textures, warm studio lighting,
  4. post-processing, twelve beveled/lathe-turned animated 1×1 props, professional
  5. docs, QA, and a verified GitHub release.
  6. - **Skill:** [`SKILL.md`](SKILL.md)
  7. - **Reference app:** https://github.com/yx0128/terracotta-courtyard-3d
  8. - **Skill repo:** https://github.com/yx0128/terracotta-courtyard-3d-skill
  9. - **References:** build playbook, art/lighting rules, release checklist.
  10. Install by copying this folder to `~/.claude/skills/terracotta-courtyard-3d/`
  11. (and optionally `~/.config/opencode/skills/`). Load it when a task asks for a
  12. procedural miniature diorama, R3F lighting/material study, or a complete
  13. Phase 1→2 3D web build with no external assets.
  14. MIT © 2026 Terracotta Courtyard contributors.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.