Skip to content
Back to search

ascii-diorama

SkillWorks with Claude CodeGitHub

Build tilt-shift ASCII miniatures, which are small, dense, living 3D worlds in Three.js drawn entirely as coloured monospace characters and seen from high above with the top and bottom of the view blurred like a scale model. Use when someone asks for an ASCII scene, ASCII shader or renderer, glyph-rendered or text-mode 3D, an ASCII diorama or miniature, a tilt-shift ASCII effect, or a dense little world (village, harbour, coast, forest path, shrine, city block) in this style. The result is a live web page that animates and loops.

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/jdhruv14--ascii-diorama/badge.svg)](/listings/jdhruv14--ascii-diorama)

HTML

<a href="/listings/jdhruv14--ascii-diorama"><img src="/api/listings/jdhruv14--ascii-diorama/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/JDhruv14/ascii-diorama ~/.claude/skills/ascii-diorama

Claude Code picks it up automatically. Ask for something like "an ASCII diorama of a fishing harbour", or run `/ascii-diorama`.

To update later:

git -C ~/.claude/skills/ascii-diorama pull

Requirements

- Node.js 18+ - `three` and `esbuild` installed in or above the scene folder:

  npm i three esbuild

- A browser with WebGL 2

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 · 96 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ascii-diorama
  3. description: Build tilt-shift ASCII miniatures, which are small, dense, living 3D worlds in Three.js drawn entirely as coloured monospace characters and seen from high above with the top and bottom of the view blurred like a scale model. Use when someone asks for an ASCII scene, ASCII shader or renderer, glyph-rendered or text-mode 3D, an ASCII diorama or miniature, a tilt-shift ASCII effect, or a dense little world (village, harbour, coast, forest path, shrine, city block) in this style. The result is a live web page that animates and loops.
  4. ---
  5. # ASCII diorama
  6. Build a small, dense, animated 3D world and draw it as coloured monospace glyphs, seen from high above through a long lens. Each glyph cell takes its colour from the 3D render, and its character from what the surface is, how bright it is and which way its edges run. The middle band is sharp text; above and below, it melts into a soft painted blur, like a tilt-shift photograph of a model.
  7. The result is a live scene in the browser that animates and loops forever.
  8. ## The look
  9. - **Camera**: about 52 to 58 degrees down, FOV about 23, around 70 to 80 units from the subject. It sweeps slowly back and forth over about 14 degrees of yaw with eased turns and a slight push in. Nothing cuts.
  10. - **Composition**: one leading line runs diagonally through the view, such as a stair path, shoreline, river or street. A single saturated focal colour sits against calmer greens, golds and creams. A strong focal colour is one like vermilion gates, striped parasols or a yellow tram. Something different fills the top band (a canopy, rooftops) and the bottom band (water, a plaza) so the blur has colour to work with.
  11. - **Density**: everything is many small things. That means tens of thousands of grass blades, thousands of leaf cards clustered into tree crowns with dark gaps, flower cards in noise-shaped patches, rows of repeated props (lanterns, steps, posts) and rocks along the edges. Sparse, smooth, low-poly scenes read as toys.
  12. - **Life**: wind moves the grass and leaves. Water rolls in bands of foam and pulls back up the shore. Petals or motes drift across. One small creature or figure walks through the focal area.
  13. - **Glyphs**:
  14. - grass in `/ | \` strokes that lean with the wind
  15. - foliage in `. : * + o`
  16. - stone and steps in `— = #`
  17. - water in `- ~ =`, with foam in `* % #`
  18. - creatures in `$ &`
  19. - strong edges switch to `| / — \` along their direction
  20. The cell background is a dim, blurred copy of the render, so gaps between glyphs still carry colour.
  21. ## Files
  22. - `templates/scene/main.js`: the complete starter miniature, which is red gates running down a green cliff to a turquoise sea. It includes stone steps, lanterns, gold and red trees, white flower patches, rocks with foam, a walking fox and drifting petals. Every system you need is in it: terrain bake, sea shader, instanced grass, flowers and leaves, path props, the glyph pass and tilt-shift. It runs live and loops; Space pauses.
  23. - `scripts/fetch-assets.sh <scene-dir>`: downloads the starter's textures and fox model.
  24. - `scripts/serve.mjs <scene-dir> [port]`: bundles the scene and serves it, rebuilding on every reload.
  25. ## Workflow
  26. 1. **Start from the template and change the subject.** Don't ship the template's subject unchanged. Keep the systems and swap what they build, so it becomes your own world. For example:
  27. - a fishing harbour with a breakwater path and boats
  28. - a hill village with a cobbled lane
  29. - a waterfall gorge with a footbridge
  30. - a lighthouse point
  31. - a desert oasis
  32. - a city rooftop garden
  33. ```bash
  34. mkdir -p <scene> && cp ~/.claude/skills/ascii-diorama/templates/scene/* <scene>/
  35. bash ~/.claude/skills/ascii-diorama/scripts/fetch-assets.sh <scene>
  36. ```
  37. It needs `three` and `esbuild` resolvable from the folder (a parent `node_modules` works).
  38. 2. **Know where things live in `main.js`**:
  39. | Section | What it controls |
  40. |---|---|
  41. | `coastZ`, `rawH`, `ROCKS` | the land shape and shoreline |
  42. | `PATH` | the leading line, as control points from top to bottom of the view |
  43. | `buildTerrain` | bakes ground colour and glyph class from real textures, zoned by height, path distance and noise |
  44. | `buildSea` | the water: depth colours, rolling foam, swash, caustics |
  45. | `buildGrass`, `buildFlowers`, `buildTrees` | the dense fill |
  46. | `buildTunnel`, `buildLanterns`, `buildShrine`, `buildRocks` | the props along and around the path; replace these with your subject's props |
  47. | `CLS` and the `cls<...` branches in `asciiFrag` | the glyph rules per surface |
  48. | `placeCamera`, `TARGET`, `DURATION` | the sweep and its period |
  49. | `tiltFrag` | the focus band and blur strength |
  50. | `COLS`, `ROWS`, `W`, `HH` | glyph grid and canvas size |
  51. 3. **Gather assets with clear licences.** Prefer CC0:
  52. - Poly Haven textures and HDRIs: `https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/<id>/<id>_diff_1k.jpg`, with the list at `https://api.polyhaven.com/assets?t=textures`.
  53. - Khronos glTF sample models: read each README's Legal section.
  54. Put downloads in their own folder, never run anything from them, and keep a list of each asset's source and licence. Avoid copyrighted characters.
  55. 4. **Look at it while you build.**
  56. ```bash
  57. node ~/.claude/skills/ascii-diorama/scripts/serve.mjs <scene>
  58. ```
  59. Open the printed URL, reload after each edit, and take screenshots to judge it. Check that the focal element and the leading line sit in the sharp band, that the top and bottom bands hold colour, and that large areas sit in the middle brightness range so their glyphs vary.
  60. 5. **Check motion, not just stills.** Pause with Space at a few moments, or take several screenshots in quick succession. Glyphs flipping every frame read as strobing, so slow down the noise that drives them. The creature should step, not slide.
  61. 6. **Hand it over.** The scene folder runs with `serve.mjs`. For a static copy, `index.html`, `build/main.js` and `assets/` are everything the page needs, and they can go on any static host.
  62. 7. **Report**: say how to view it, list each asset with its source, licence and any credit needed, and name any weak spots you saw.
  63. ## Tuning that works
  64. - Grid 200×100 on a square canvas (cells of about 7×14 px). Sample the scene at the cell's mip level so each glyph averages its footprint.
  65. - Grade: tone curve, saturation 1.2 to 1.4, glyph colour × 1.3, cell background × 0.2 to 0.35. Raise the background for large bright surfaces such as sand or snow so they stay light.
  66. - Tilt-shift: focus around 0.42 to 0.47 of the height, blur starting about 0.27 away from it, up to 26 to 30 px on a golden-angle disc.
  67. - Light: a low-ish sun from the front-left with 4096 shadow maps, so canopies throw dappled shadow onto the grass and props cast readable shadows. Use a warm hemisphere fill.
  68. - Props on a path: space them at about the prop width, never tighter. Use a long gentle S rather than tight switchbacks.
  69. - Anything time-driven should loop cleanly or ping-pong, so the live view never jumps.
  70. ## Pitfalls seen before
  71. - **Props lying along the path instead of across it**: with local x as the wide axis, use `rotation.y = Math.atan2(tangent.x, tangent.z)`.
  72. - **Tight switchbacks under wide props**: they pile into a claw shape.
  73. - **Black squares spreading through the image**: NaN in the half-float target, which mipmapping spreads. Lit skinned glTF meshes are the usual cause, so use `MeshBasicMaterial` for small animated creatures.
  74. - **Hulls or roofs black from above**: flipped normals on extruded shapes. Use `side: THREE.DoubleSide` or unlit materials.
  75. - **Dark tops on gates or roofs**: these hide the focal colour from a steep camera, so colour the top surfaces.
  76. - **Water blowing out to white glyphs**: lower its base colours.
  77. - **Orange or brown blob rocks**: tint them cool grey and flatten them.
  78. - **A glyph used in a rule but missing from `GLYPHS`**: it produces `undefined` in the shader, so add it to the atlas string first.
  79. - **Someone else's browser view**: never navigate, resize or click in a browser someone is watching just to verify. Open your own tab or a separate headless browser instead.
README.md · README · 97 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ascii-diorama
  2. A [Claude Code](https://claude.com/claude-code) skill for building **tilt-shift ASCII miniatures**: small, dense, living 3D worlds drawn entirely as coloured monospace characters.
  3. The camera looks steeply down on a little Three.js diorama and sweeps slowly back and forth while the top and bottom of the view blur away like a scale model. Every pixel is drawn as a glyph:
  4. - grass as `/ | \` strokes that lean with the wind
  5. - water as `~ -` with `#` foam
  6. - stone as `— = #`
  7. - trees as clusters of `o * +`
  8. Each glyph takes its colour from the 3D render. Up close it reads as text, and from a distance as a painting. It runs live in the browser and loops forever.
  9. ## What's inside
  10. ```
  11. SKILL.md the skill: look, workflow, tuning, pitfalls
  12. scripts/serve.mjs live preview that rebuilds on every reload
  13. scripts/fetch-assets.sh downloads the starter scene's textures and model
  14. templates/scene/main.js a complete starter miniature (Three.js)
  15. ```
  16. The starter scene is a line of red gates running down a green cliff to a turquoise sea. It has stone steps, lanterns, gold and red trees, white flower patches, rocks with rolling foam, a walking fox and drifting petals.
  17. It contains every system a new scene needs:
  18. - terrain baking from real textures
  19. - a sea shader
  20. - instanced grass, leaves and flowers
  21. - path props
  22. - the glyph pass and tilt-shift
  23. Swap what those systems build to make your own world, such as a harbour, a hill village, a gorge, a lighthouse or a rooftop garden.
  24. ## Install
  25. ```bash
  26. git clone https://github.com/JDhruv14/ascii-diorama ~/.claude/skills/ascii-diorama
  27. ```
  28. Claude Code picks it up automatically. Ask for something like "an ASCII diorama of a fishing harbour", or run `/ascii-diorama`.
  29. To update later:
  30. ```bash
  31. git -C ~/.claude/skills/ascii-diorama pull
  32. ```
  33. ### Requirements
  34. - Node.js 18+
  35. - `three` and `esbuild` installed in or above the scene folder:
  36. ```bash
  37. npm i three esbuild
  38. ```
  39. - A browser with WebGL 2
  40. ## Use it by hand
  41. Set up a scene from the starter:
  42. ```bash
  43. mkdir -p my-scene && cp ~/.claude/skills/ascii-diorama/templates/scene/* my-scene/
  44. bash ~/.claude/skills/ascii-diorama/scripts/fetch-assets.sh my-scene
  45. ```
  46. Run it:
  47. ```bash
  48. node ~/.claude/skills/ascii-diorama/scripts/serve.mjs my-scene
  49. ```
  50. Open `http://127.0.0.1:5173/`. Reload the page after editing `my-scene/main.js`, and press Space to pause.
  51. For a static copy, `index.html`, `build/main.js` and `assets/` are everything the page needs.
  52. ## How it works
  53. 1. Each material writes a surface class (grass, water, stone and so on) into the alpha channel of a half-float render target.
  54. 2. A full-screen shader splits the view into a 200×100 grid. For each cell it samples the render at the matching mip level, reads the class and measures the brightness gradient. It then picks a glyph from a per-class rule, with wind noise for grass and water and edge direction for stone.
  55. 3. The glyph is drawn from a canvas-generated atlas, coloured with the graded render colour, over a dim blurred copy of the scene.
  56. 4. A tilt-shift pass blurs the top and bottom bands on a golden-angle disc.
  57. ## Asset licences
  58. `fetch-assets.sh` downloads the following (none of these files are stored in this repo):
  59. | Asset | Source | Licence |
  60. |---|---|---|
  61. | Textures: `leafy_grass`, `coast_sand_01`, `aerial_rocks_02`, `castle_wall_slates`, `weathered_planks`, `bark_brown_02` | [Poly Haven](https://polyhaven.com) | CC0 |
  62. | Fox model | PixelMannen, via [Khronos glTF Sample Assets](https://github.com/KhronosGroup/glTF-Sample-Assets/tree/main/Models/Fox) | CC0 |
  63. | Fox rig and animation | tomkranis | CC BY 4.0, credit required |
  64. | Fox glTF conversion | @AsoboStudio and @scurest | CC BY 4.0, credit required |
  65. If what you publish shows the fox, credit tomkranis, @AsoboStudio and @scurest.
  66. ## Licence
  67. The code and skill text in this repository are released under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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