From c04d99fe384a83a96bb67cb3b31c1f39d3e6e5e4 Mon Sep 17 00:00:00 2001 From: hypercross Date: Sat, 8 Aug 2026 18:28:56 +0800 Subject: [PATCH] docs: document object viewers and asset proxy --- README.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 47b8b6d..9a42384 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,11 @@ analyze their contents. A lightweight, client-only pnpm monorepo. | Package | Role | Runtime | | ------------------- | ------------------------------------------------------ | ---------- | -| `apps/web` | React frontend: search + mod pages | Browser | -| `apps/proxy` | Hono HTTP server: Workshop search + save fetch | Node | +| `apps/web` | React frontend: search + mod pages + 3D object viewers | Browser | +| `apps/proxy` | Hono HTTP server: Workshop search, save fetch, tracing | Node | | `packages/tts` | Fetch save from Steam, BSON-parse to `TTSMod` | Node | | `packages/extract` | Analyze a `TTSMod`: objects, asset refs, downloads | Isomorphic | +| `packages/mesh` | 2D shapes + extrusion into 3D mesh geometry | Isomorphic | | `packages/shared` | Shared types + zod schemas | Isomorphic | See [`docs/architecture.md`](docs/architecture.md) for the architecture and @@ -28,7 +29,7 @@ Get a Steam Web API key at https://steamcommunity.com/dev/apikey (free). To run the frontend alongside the proxy, open a second terminal and run `pnpm --filter @tts/web dev` (serves at http://localhost:5173 and proxies -`/search`, `/items`, and `/health` to the backend). +`/search`, `/items`, `/health`, `/asset`, and `/trace` to the backend). ## API @@ -38,6 +39,7 @@ To run the frontend alongside the proxy, open a second terminal and run | GET | `/search?q=&page=`| Search the Workshop (scrapes browse page) | | GET | `/items/:id` | Full parsed `TTSMod` (BSON save) | | GET | `/items/:id/file` | Raw save bytes, filename from header | +| GET | `/asset?url=` | CORS-safe proxy for external assets (textures, models) | | GET | `/trace?url=&mode=&format=&offset=` | Trace an image into a vector shape (BSON); `offset` insets/outsets in pixels | ## Commands @@ -51,6 +53,24 @@ pnpm test # run the unit tests (vitest) pnpm lint # lint all packages ``` +## Object viewers + +The mod page renders each selected object in 3D. Tiles, tokens, cards, and +custom models each have a viewer built on `@react-three/fiber`, `@react-three/drei`, +and `@react-three/postprocessing`, registered per object class and lazy-loaded +so the three.js stack is code-split out of the main bundle. + +- **Tiles / tokens** — extruded from a 2D shape; tokens trace the image's alpha + channel via `/trace` to match the artwork's silhouette. +- **Cards** — a thin rounded rect. Deck images are sheets divided into a + `NumWidth` x `NumHeight` grid; the face/back sprite is selected by `CardID` + from the containing deck's config. +- **Custom models** — GLTF/OBJ/FBX loaded from `CustomMesh.MeshURL`. + +The camera fits the object's bounds on load, and back faces are flipped so +they aren't mirrored. See [`docs/decisions.md`](docs/decisions.md) for the +rationale behind these choices. + ## How search works Steam has no official search API. The proxy fetches the Workshop browse page