Repository navigation
Releases
Threedog 2.0.0
Threedog 2.0.0, the stable release: one start command, new games that open lit and in color, and a reset order you can rely on. Some 1.x games need a small change to upgrade (below).
npm install threedog@2 @threedog/tools@2
npx threedog init my-gameEvery change is in the changelog.
Upgrading from 1.x
- Install the packages together at 2.0 (
threedog,@threedog/tools, and@threedog/post-effects,@threedog/terrain-noiseif you use them). Thethreedogcommand now comes with thethreedogpackage. characters()requiresworld(): add it before,engine.use(world(), collision(), characters()).openWorld()already has it.- On newGame and load, a game's own
world:loadlistener now runs after the player is placed back. Code that relied on running first moves into a module'sworldLoad(e, info)hook. - Something your picture sizes from
engine.tierwhen it is made (a shadow map, a light count) follows a later change only if it listens to the newtier:changeevent.
Start
npm install threedog @threedog/toolsandnpx threedog initis the one way in; the README andllms.txtopen with it. A missing tools package prints the install line.- New games start from a neutral daytime picture instead of grey: sun with soft shadows, the sky as the fill light, tone mapping, ambient occlusion and a light bloom, a temperate sky, muted ground, water and player colors. All of it is plain three.js in the game's own
picture/folder, and the generatedCLAUDE.mdsays it is a placeholder to restyle. - A new game's
CLAUDE.mdhas a "Before you call it done" checklist: comparethreedog shotwith the target style.
Fixed
- On WebGPU,
engine.sky.environment()stalled the game at each rebuild (100 ms to seconds, once a second while the sky moved). The same map is now refilled. - Adding a pass that only reads the scene render (such as
GTAOPass) toengine.postblanked the screen. - Ambient occlusion on WebGPU was grainy; it is denoised.
start()resolved before a module that waited for a replaced provider had finished its init, and a critical one failing there did not stop the start.- On test and screenshot pages, a halt taken and removed left the engine running in real time.
- After a lost WebGL context came back, adaptive resolution could stay low for good.
- Physics solver settings were lost on newGame and load.
New
tier:changeevent; particles, weather, terrain color detail, shadow cascades and post effects follow a tier change while running.- The newGame / load reset runs in one declared order (
sessionEnd,worldLoad,sessionStarthooks on a module), no longer in install order. engine.sky.keyframes()with no argument returns the rows in use.threedog perfmeasures for a duration: 2 s warm-up, three runs, average FPS, 1% low and spike frames.- Screen shake without taking the camera (recipe 21 §6b).
Tools
- One browser lifecycle for shot, perf, stress, capture, gallery and bake: a failed launch closes everything it opened and prints one line with the fix. A missing browser says
npx playwright install chromium. threedog initwarns when a keptindex.html, vite config or dev script would keep the game from starting.
Tested on Chrome on Windows (D3D) with real WebGPU, one NVIDIA laptop GPU: 11,155 checks, all pass apart from one WebGPU path-trace photo test that timed out under load (left as is).
中文摘要: 2.0.0 正式版。新项目一条命令起步,打开就有正确的光照和中性配色;新开一局和读档的重置顺序固定下来;修好了 WebGPU 上天空当光源时卡顿、部分后期效果整屏变空等问题。从 1.x 升级:几个包一起升到 2,用了 characters() 的游戏要先装 world(),详见上面的 "Upgrading from 1.x"。
Threedog 1.3.0
Threedog 1.3.0: WebGPU failures now name their cause, and a showcase scene can start without content.
npm install threedog@1.3.0 @threedog/tools@1.3.0Every change is in the changelog.
Fixed on WebGPU
- The engine asks the device for the adapter's own buffer, storage, texture and sampler limits instead of WebGPU's defaults.
voxelGIon a scene of a million triangles or more no longer fails every frame withBuffer size exceeds the max buffer size limit. sunShaftscompiles on D3D backends that use FXC. Shadow map compares are written astextureSampleCompareLevel(same picture), listed indescribe().threePatchesascompare-sample-level.- A post effect whose own pass the device refuses to build is held off and the frame draws without it.
describe().render.postshowson: falsewith the reason, and the page error has the codepost-effect-failed. Before, the effect showed as on while every frame was invalid. - A material that binds more textures or samplers per shader stage than the device allows stops at its build with a
texture-bindingserror naming the material, the mesh and the counts, instead of the device'sInvalid PipelineLayout.
New
threedog init --scene-onlystarts a showcase scene with a camera,picture/, start screen, autosave and Esc menu, and nocontent/and noassets.js.views.show({ position, target, fov })shows a pose with no view declared.threedog state view=x,y,z,tx,ty,tz[,fov]places the camera on a running page beforethreedog snap.
Changed
engine.budgethas a default guide of 7 forshadowMaps(a point light is six maps). Nothing is cut at it;engine.budget.enable({ shadowMaps: n })sets your own. The picture check prints the frame's triangles with it.
Tested on Chrome on Windows (D3D) with real WebGPU, one NVIDIA laptop GPU. Holding a refused post effect was run on that machine only. An effect that is only an expression, with no pass of its own, is still named by material only and is not held.
Threedog 1.0.0
Threedog 1.0.0: a three.js game engine built for AI agents.
npm install threedog @threedog/tools
npx threedog init my-gamePackages on npm: threedog, @threedog/tools, @threedog/post-effects, @threedog/terrain-noise.
Upgrading from 0.x: read MIGRATING-1.0.md. Every change is in the changelog.
What 1.0 settles
- Saves, new games and loads take turns, and a failed load puts the game back as it was.
content.loadis one transaction and returns a Promise.- One writer for each thing: only the holder in charge moves the camera or a character.
- The AI tools:
threedog howbrowses every capability by category, and every recipe code block runs in the test suite.
Tested on Chrome and Edge on Windows with real WebGPU and WebGL. Multiplayer is experimental. Safari, macOS, phones and tablets have not been run. The full list is under Status and known limits.