storyai-3d-director-desk: a browser 3D director desk for previz and shot blocking
A browser-based 3D director desk demo built with React, Vite, and Three.js.
At a glance
- What is it?
- storyai-3d-director-desk is a React, Vite and Three.js demo for lightweight previz: place characters, cameras and panoramas in a browser viewport, then capture shots. The README documents the workflow well and the test suite honestly, but it ships as a source demo rather than a finished tool.
- Who is it for?
- Adopt storyai-3d-director-desk if you want a readable starting point for a browser previz tool and are willing to work in TypeScript: the store, loaders and runtime folders give you characters, poses, camera capture and local persistence already wired. Do not adopt it as a finished product, and do not expect a hosted service, since the README points to no homepage and the version is 0.0.1.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 77 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 20, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What storyai-3d-director-desk is for, and who it is not for
The project calls itself a 3D storyboard director desk (3D分镜导演台). The problem it addresses is the gap between a written shot list and a rendered frame: you need to know where a camera sits, how tall a character reads against a background, and whether a crowd of thirty extras fills the frame the way you imagined. The README lists the pieces that answer those questions: switching between a director view and a camera view, eight built-in characters with twenty poses, quick placement of characters, extras, primitives and cameras, FBX and OBJ import, a crowd array, panorama import with background adjustment, camera capture with screenshot records and basic shot management, viewport aspect frames and a rule-of-thirds grid, and local scene persistence.
That is a previz surface, not a renderer. There is no mention of lighting rigs, materials authoring, animation timelines or export to a production pipeline beyond project JSON. If your goal is a final frame, this is the wrong tool. If your goal is deciding whether a shot works before anyone books a stage, the feature list maps onto that job closely. The audience is a developer or a small studio that wants to embed a viewport into a larger creative workbench, which the README supports by noting the component ships with a host page communication bridge.
How the viewport, store and loaders fit together
The repository layout in the README is the clearest description of the architecture, and it is worth reading before the source. src/app/layout holds the top-level shell that organizes the canvas and the two sidebars. src/editor/canvas contains the Three.js and React Three Fiber viewport, the aspect frame, the toolbar and the screenshot view. src/editor/panels holds the object tree on the left and the property panel on the right. src/editor/store is Zustand state management plus undo and clipboard logic. src/editor/io handles screenshot export, project import and export, and host communication. src/editor/loaders imports local models and panoramas. src/editor/runtime renders characters and applies skeletons and poses. src/editor/schema defines the data structures, cameras and viewport types. src/styles holds global styles.
The data flow follows that split. Objects are added from the toolbar or the panels, they land in the Zustand store, and the store drives both the object tree and the property panel, which is why the README says the right panel switches automatically between scene, character, model and camera editors based on the current selection. Undo and the clipboard live in the same store, so Ctrl/Cmd + Z, Ctrl/Cmd + C and Ctrl/Cmd + V operate on the same object graph the viewport renders. Persistence goes to browser localStorage for the current scene and the local model library, and the README separately describes exporting and re-importing a project JSON, plus saving and restoring a recent project. Two persistence paths exist, and the README does not say how they reconcile if you edit a restored project and then export it.
The stack is pinned in package.json: React 18.3, Vite 6.1, TypeScript 5.7, three 0.184, @react-three/fiber 8.17, @react-three/drei 9.122, camera-controls 2.9, Zustand 5.0 and lucide-react for icons, with Vitest 4.1 and Testing Library for tests. Nothing here is exotic. The one dependency worth flagging is @rollup/rollup-darwin-arm64 in devDependencies, which is a platform-specific binary and will not help on other architectures.
Install and block your first shot
The README gives the install steps directly, and there is no separate setup script. Clone the repository, then run the two npm commands. The README says the dev server normally comes up at http://127.0.0.1:5173/, and that if the port is taken Vite moves to the next available one, so read the terminal output rather than assuming the address.
npm install
npm run devOnce the page loads, the README describes the working pattern: the top of the interface switches between director view and camera view; the left side searches, selects and groups scene objects and offers visibility, lock and delete; the center viewport is where you place objects, change transform mode, add characters and cameras, import assets and take screenshots; the right panel changes to match whatever is selected. A first pass at a shot is therefore: add a camera, add a character, switch to camera view, and adjust until the framing reads.
Keyboard handling is limited but stated: Ctrl/Cmd + C copies the selected object, Ctrl/Cmd + V pastes it, Ctrl/Cmd + Z undoes the last operation, and Delete or Backspace removes the selection. For a crowd, the README describes a crowd array rather than repeated pasting, which is the faster route when you need many figures.
To check a production bundle, the README documents two more scripts. npm run preview serves the built output, normally at http://127.0.0.1:4173/, and npm run build compiles TypeScript and then bundles with Vite.
npm run build
npm run previewThe README reports that npm run build passes but emits Vite warnings: some model library thumbnail URLs are resolved at runtime, and the main bundle exceeds the default chunk size warning threshold. Treat both as things to measure in your own build rather than as defects.
The test suite is not green, and the README says so
The most useful sentence in the README is the test status: npm test currently passes 304 of 312 cases, and the remaining 8 failures cluster around the model library panel, the viewport aspect frame and axis hit areas, individual pose presets, and style assertions. That is unusually candid for a demo repository, and it should shape how you read the rest of the feature list.
The failures are not random. Model library panel and pose preset failures sit in the parts of the product that depend on imported or bundled assets, which is exactly where a demo tends to drift as assets change. Style assertions failing means the test suite is partly pinned to presentation, so a visual refactor will break tests that have nothing to do with behavior. Viewport aspect frame and axis hit area failures touch interaction geometry, the code that decides whether your click landed on the frame or the axis handle. If you plan to change the viewport, expect to fix those tests first, because they describe behavior that is currently wrong or at least unverified.
A second limitation is asset licensing. The README states that if you publish based on this project you must confirm the distribution license for any new models, textures and scene assets you add. The repository itself is MIT, but MIT covers the code, not the character models or panoramas you bring in. Local FBX and OBJ import means you will bring in assets, and the README places that responsibility on you.
Where a browser previz demo stops being the right choice
The honest boundary is that this is a source demo, and the README says as much: the repository is primarily a source demonstration, suitable for continued extension into a more complete 3D director tool. The package version is 0.0.1 and there are no releases listed. If you need a tool your team can open tomorrow without a build step, this is not it.
Scale is the second boundary. Everything runs in the browser, the scene and model library live in localStorage, and the README notes the main bundle already exceeds Vite's default chunk warning threshold. A crowd array can add many figures quickly, and nothing in the README describes instancing limits, level-of-detail handling or a cap on object count. Before committing to a scene with hundreds of characters, you would want to measure frame time yourself, because the README gives no performance figures at all.
The third boundary is collaboration. Persistence is local to one browser profile plus manual JSON export and import. There is no server, no account, no shared project state. Two people cannot work on the same scene simultaneously, and the README does not document any merge behavior for imported project files. If your previz process requires a shared, versioned scene, you will be building that layer yourself on top of the io folder.
Finally, the README does not document rollback beyond a single undo step in the store, and it does not describe what happens to localStorage when a project JSON is imported over an existing scene. Those are the two places I would read the source before trusting the workflow.
How it differs from Blender as a previz stage
The obvious alternative for shot blocking is Blender, which is free, mature, and has a full animation and rendering pipeline. The difference is not quality, it is where the work happens and who can do it. Blender is a desktop application with a real scene graph, keyframes, rigging tools and a render engine. storyai-3d-director-desk is a browser page with a fixed set of eight characters and twenty poses, a crowd array, panorama backgrounds, camera capture and JSON project files.
That narrower surface is the point. Blocking a shot in Blender means opening a file, managing a project structure and knowing the transform and camera tools. Blocking a shot here means loading a page, dropping in a character and a camera, and taking a screenshot, with the README describing the whole interaction model in a handful of bullet points. The trade is capability for speed of entry, and for a director or editor who does not live in a 3D application, that trade can be worth it.
The other difference is embedding. The README states the components include a host page communication bridge and are suited to being embedded in a larger creative workbench. Blender cannot be embedded in your web product. If you are building a storyboarding or production tool and want a viewport inside it, this repository is closer to what you need than any desktop application, provided you accept that you are starting from a demo with a partly failing test suite.
Maintenance, upgrade cost and the MIT license in practice
The last push to the default branch was on 2026-07-06. The repository is not archived. There are no releases listed, and the package version is 0.0.1, so there is no upgrade path to reason about yet: you would be tracking main directly rather than pinning a version.
Upgrade cost comes from the dependency set rather than from the project's own code. React 18, Vite 6, three 0.184, @react-three/fiber 8 and @react-three/drei 9 are all moving targets, and react-three-fiber in particular has had breaking changes between major versions. Because the project pins these with caret ranges in package.json, a fresh npm install can pull newer minor versions than the author tested against. The README's build and test results are a snapshot of one such install, and the eight failing tests are part of that snapshot. If you fork this, commit a lockfile-driven install and re-run npm test before and after any dependency bump, so you can tell a new failure from one of the eight already documented.
The license is MIT, stated in both the README and package.json. That covers the source in this repository. The README is explicit that you must confirm the distribution license for any models, textures and scene assets you add, and since the product is built around importing local FBX and OBJ files and panoramas, that is the practical constraint rather than the code license. I am not a lawyer and this is not legal advice; the point is that the asset question is the one the README raises, and it is the one that will bite a published project.
Editorial conclusion
Adopt storyai-3d-director-desk if you want a readable starting point for a browser previz tool and are willing to work in TypeScript: the store, loaders and runtime folders give you characters, poses, camera capture and local persistence already wired. Do not adopt it as a finished product, and do not expect a hosted service, since the README points to no homepage and the version is 0.0.1. Before you build on it, run npm test and read the eight failures listed in the README, check that your own model and texture assets carry distribution rights, and confirm the bundle size warning that npm run build reports, because the README says the main chunk exceeds the default threshold.
Frequently asked questions
How do I install storyai-3d-director-desk and run it locally?
Clone the repository and run npm install followed by npm run dev. The README says the dev server normally comes up at http://127.0.0.1:5173/, and that Vite moves to the next free port if that one is taken.
Does storyai-3d-director-desk pass its own test suite?
No. The README reports 304 of 312 cases passing, with the remaining 8 failures concentrated in the model library panel, viewport aspect frame and axis hit areas, individual pose presets, and style assertions.
Can I import my own models and panoramas into storyai-3d-director-desk?
Yes. The README lists local FBX and OBJ model import with a customizable model library, plus panorama import with background adjustment. It also states that you must confirm the distribution license for any models, textures and scene assets you add.
Where does storyai-3d-director-desk store my scene?
The README says the current scene and the local model library are written to browser localStorage. It also supports exporting a project JSON and re-importing it, plus saving and restoring a recent project.
Community notes