tinyworld-lowpoly-stylized-3d

name	tinyworld-lowpoly-stylized-3d
description	Use when adding, importing, designing, reviewing, or animating low-poly / stylized 3D assets in Tiny World Builder, including Three.js procedural meshes, GLB/GLTF assets, Poly Pizza models, material palettes, scale/orientation, silhouettes, clouds/planes/crop dusters, and toolbar thumbnails.

Tiny World Low-Poly Stylized 3D

Use this together with:

• Project skill .codex/skills/tinyworld-single-file/SKILL.md for single-file constraints.
• Project skill .codex/skills/tinyworld-render-performance/SKILL.md for GPU/shadow/renderer limits.
• Installed skill .agents/skills/3d-modeling/SKILL.md for topology, UV, export, LOD, and GLB hygiene.
• Installed skill .agents/skills/poly-pizza-api/SKILL.md when sourcing low-poly models from Poly Pizza.
• Installed skill .agents/skills/lightweight-3d-effects/SKILL.md when adding decorative lightweight 3D effects.

Tiny World art direction

• Low-poly, toy-like, readable at thumbnail size.
• Chunky primitives with bevels/rounded slabs, not realistic detail.
• Strong silhouettes beat micro-detail.
• Bright but not washed out: use saturated local color plus darker trim/shadow-side material.
• Keep texture use rare and intentional. Procedural THREE.MeshLambertMaterial colors should remain the default for built-in objects.
• Custom/generated voxel stamps should not render full bounding-cage trim by default; reserve bounds frames for explicit decorative-outline stamps.
• If generated voxel stamps include a broad ground/platform part, sink that base into the terrain rather than showing a raised tile under the object.
• Use flat/Lambert lighting semantics compatible with the vendored Three.js r185 global bundle.
• Avoid glossy/PBR realism unless an imported asset already depends on it.

Scale rules

• One grid tile is 1 x 1 world unit.
• Small props should fit comfortably inside a tile: ~0.2–0.8 units wide.
• Houses can occupy one or multiple tiles, but doors/windows must remain readable from the default camera.
• Flying ambient objects should be scaled to feel like toys above the board, not real-world aircraft; crop duster wingspan target is around 1–1.5 tiles.
• Always normalize imported model scale with Box3 bounds, then apply a target span.
• Apply orientation fixes once at model root or a named wrapper; do not keep stacking ad-hoc rotations in the animation loop.

Voxel avatar descriptors

• Keep window.voxelAvatarDescriptor in engine/world/53-voxel-avatar.js and cleanAvatar in party/index.js in lockstep. The networked Tinyverse descriptor currently allows kind, seed, body, skin, hairC, hair, fit, head, height, build, and gear.
• Voxel avatar gear should use simple cached/shared geometries and materials where possible. Mark shared gear meshes with userData.sharedAvatarAsset so the avatar dispose path does not dispose shared assets while removing one avatar instance.

Material and palette rules

• Prefer 2–4 materials per object: body, dark trim, highlight, accent.
• Bespoke generated voxel/custom-part models should use semantic material families rather than collapsing to the seed material. A greenhouse needs glass + frame + planting/base materials; an airship needs hull + brass/copper machinery + fabric/canvas balloon panels + cable/rope rigging + glass bridge/window accents.
• Generated custom-part renderers must keep those semantic families editable after creation. voxelAppearanceMaterial() should apply global materialTexture even when a part has no inferred body/top role, and body/top colours or textures should override only parts whose material/color maps to the matching role.
• Use the custom-part cable primitive for actual connections: balloon ropes, crane lines, tethers, rigging, moorings, bridge suspension lines, and other angled cords. Do not fake these as vertical stone/wood columns when endpoints are known.
• Use custom-part sphere/ellipsoid primitives for rounded balloon envelopes, domes, tanks, and soft canopies. Panel bands or ribs can be boxes only when they read as raised seams; colored balloon fabric panels should use curved ellipsoid slices (phiStart/phiLength) rather than square side plates.
• Default custom-part stamps should be board-scale on first creation. Compact bridges, decks, docks, and props should be about one tile wide and can use a small negative Y offset to sit into the terrain/water; only deliberate hero objects should claim 1.5+ tiles.
• Native TinyWorld objects can be used as parts of a scene, but they should not stand in for a requested model when customParts can express the model directly.
• Never mutate shared M.* material colors for one instance; clone or create a new material. The one allowed global exception is applySeasonFoliage(), which centrally retints shared foliage/grass materials for season changes.
• MeshLambertMaterial does not provide the same flatShading workflow as Standard/Phong; keep faceted model-stamp fallbacks through non-indexed/flat-normal geometry instead of unsupported material flags.
• Built-in material references should live in engine/world/04-textures.js as deterministic coarse canvas textures before adding per-object overrides. Current coarse material maps include path-pavers, castle-block, brick-building, roof-shingles, window-lit, window-unlit, , , , , , , sunflower maps, and . Keep them intentionally large and calm from the default/top-down camera; if the whole island reads noisy, lower world-UV repeat before adding detail. Ground path is brick/paver blockwork, not rock chips or gravel: keep path terrain on and avoid loose pebble overlays that make it read as stone rubble. Ground grass and ground stone default back to the older calm / maps; use the newer coarse maps on object materials, side panels, or explicit user-selected terrain texture overrides instead. Stone riser/side faces use a separate large-block material () so cliffs can scale up without changing the stone ground cap. Home island edge grass/soil/rock strata is not a texture-map option: it is the dedicated shader material, aligned from (the visible grass-cap top) down a shallow side backing behind the foreground greebles. It samples , a fixed 1024x192 horizontal strata slice; keep that slice image-driven and the same dimensions rather than rebuilding tall normalized procedural bands. Grass richness should stay FPS-safe through shared texture maps ( or only when intentionally selected), not added blade meshes. Stone blocks should stay light cool gray like the stair/column references rather than tan or charcoal; fence timber should stay warm and use horizontal grain bands so rails read correctly.

Model import hygiene

• Keep assets under models/ and ensure publish.sh copies them to dist/models/.
• Use the vendored Three.js r185 GLTF stack from vendor/three/tinyworld-three.r185.min.js (GLTFLoader, DRACOLoader, MeshoptDecoder, and KTX2Loader) and configure the loader before loading imported model stamps. Surface remaining unsupported-extension errors instead of silently showing the generic placeholder.
• After loading:
  1. compute Box3, center model at origin,
  2. scale to target tile/world size,
  3. set cast/receive shadow intentionally,
  4. tag moving subparts in userData,
  5. dispose cloned materials/geometries if removed.
• Search named nodes before doing geometry surgery. Common names: prop, propeller, blade, rotor, fan, wheel, flap.

Animation rules

• Animate only transforms and opacity.
• Respect the existing userData.landing pattern for placed cell objects.
• For propellers: wrap or find the named prop mesh, spin around its local blade axis every frame, and add a translucent disc for high-RPM readability. For TinyWorld-built lift engines, keep the fan plane centred on the lower shaft mount, prefer a shared dark shader blur/strobe disc, and hide physical blade groups once the spin ramp reaches speed.
• For rocket/jet flames: prefer chunky pixel/block shader sheets or capped particle pools over many animated micro-meshes. Preserve the toy-like silhouette with a plume that narrows toward the bottom, hard flicker bands, and warm core/outer colours rather than realistic volumetric fire. When replacing an object style, keep the older object factory as an inactive legacy helper instead of deleting it.
• For aircraft: use shallow easing, pitch with climb/descent slope, and bank during turns. Do not teleport or dive straight down into the board.
• Small world motion is preferred over heavy renderer tricks: tree asymmetry, crop/wheat/corn/sunflower sway, window glow, smoke, waterfalls, clouds, and engine movement should sell life while keeping object roots in the existing animatedCellObjects/runtime sets.
• Particle effects should be capped and use cheap cloned MeshBasicMaterial; dispose particle materials when particles die.

Validation checklist

• Inline script passes: perl -0ne 'print $1 if m#<script>\s*(.*?)\s*</script>#s' tiny-world-builder.html | node --check.
• ./publish.sh copies any new assets into dist/.
• Default camera shows the asset at the intended scale.
• Shadows are visible but not noisy; no huge new shadow casters.
• Toolbar thumbnail remains readable.
• No material mutation leaks into other objects.

Procedural cow/sheep animation

• Built-in cow/sheep meshes are created by makeVoxelAnimal() in engine/world/09b-voxel-build-factories.js and animated by engine/world/70-animal-anim.js.
• Keep animal body/head/leg pivots live: set userData.noVoxelBatch = true, expose parts under userData.anim, and register with window.__tinyworldRegisterAnimal(g) after rendering.
• Animal movement is cosmetic only. The grazer moves the rendered group around its home tile; do not mutate world[x][z] or multiplayer harvest/resource state from this animation.
• When adding new animal poses, use local state inside the 70 module and preserve the __tinyworldAnimalTick(t, dt) hook from the main animation loop.