贡献指南

July 10, 2026 · View on GitHub

感谢你对 Direct Light 的兴趣！这是一个面向导演、摄影指导和灯光师的白棚灯光预演工具。下面是参与开发需要知道的最小信息。

English summary at the bottom.

不写代码也可以参与

  • 灯光、阴影、相机或交互看起来不对：通过 Issue 表单提交复现步骤，视觉问题尽量附截图或录屏。
  • 想分享布光方案、真实片场需求，或者想法还需要讨论：到 Discussions 开一个话题。
  • 想贡献代码：先查看开放中的 Issues。较大的功能请先讨论范围；小而明确的 bug 修复可以直接提交 PR。

路线图描述的是值得探索的方向，不代表每个方向都已经决定实现。维护者会优先接收能改善导演沟通效率、并且可以通过可见结果验证的改动。

环境要求

  • Node.js >= 20.19（推荐 20 LTS 或 22 LTS）
  • npm（仓库自带 package-lock.json，请用 npm 安装以保持锁定一致）

本地起步

git clone https://github.com/oukeming64-tech/direct-light.git
cd direct-light
npm install
npm run dev        # 启动 Vite 开发服务器，默认 http://localhost:5173

其它脚本：

npm run build      # tsc -b 类型检查 + vite 生产构建到 dist/
npm run lint       # eslint .
npm run preview    # 本地预览已构建的产物

桌面版（Tauri，可选，需 Rust 工具链 + Xcode CLT）：npm run tauri dev 实时调试、npm run tauri build 出 .app/.dmg。代码在 src-tauri/，发版 CI 见 .github/workflows/release.yml；当前公开安装包见 README 顶部的 Releases 链接。Rust 依赖由提交的 src-tauri/Cargo.lock 锁定以保证构建可复现（避免上游 patch 漂移导致 CI 失败）；需要刷新锁文件时手动运行 Actions 里的「Update Cargo.lock」工作流（.github/workflows/lockfile.yml），不要在 release.yml 里临时 cargo generate-lockfile。

提交前请确保三件事都通过：npx tsc -b · npm run lint · npm run build。

代码结构在哪里

详见 ARCHITECTURE.md。一句话版本：

目录职责
src/app应用外壳与布局（AppShell 是薄布局壳，舞台/视图/对比在 Stage、compare/*）
src/scene所有 Three.js / R3F 3D 内容（白棚、人物、灯组、控光器材、相机 rig）
src/stateZustand store（store.ts 只组合 actions/* 八组工厂 + storeTypes/storeHelpers）
src/data纯数据与规格表（默认场景、渲染数值、灯具/控光附件/姿态/机位预设、场景对象）
src/domain纯业务计算（相机数学、控光器材光学、灯光简介/汇总、场景 diff/迁移、承载面）
src/ui右侧参数面板、对象列表、顶栏等 React 面板（LightPanel/ObjectList 是兼容导出壳，真实代码在 light-panel/*、object-list/*）
src/lib通用工具（颜色、几何、localStorage）

护栏：不要把实现逻辑塞回 src/ui/LightPanel.tsx、src/ui/ObjectList.tsx、src/app/AppShell.tsx 这些兼容/布局壳；新逻辑放进对应的 light-panel/*、object-list/*、Stage.tsx、domain/data 模块。src/App.tsx 必须保持薄入口。

设计取向（重要）

  • 沟通向，不是物理准确。 渲染目标是让导演一眼看懂灯位、影子、软硬、颜色关系，而不是电影级路径追踪。改动渲染时优先保证可读、稳定、实时。
  • 每次迭代都要有可见画面改进，不为技术炫技牺牲导演使用效率。
  • 渲染数值集中在 src/data/rendering.ts；改光影手感优先调这里，而不是散落到各处。
  • 渲染规则与默认灯光见 RENDERING_SPEC.md。

提交约定

  • 一次提交聚焦一件事；信息写清「做了什么 + 为什么」。
  • 涉及产品行为/视觉的改动，请说明如何在截图、录屏或应用内 A/B 对比里看到变化。
  • 改了功能、修了重要 bug 或改变实现方向，请同步更新 COLLABORATION.md 的版本记录。

当前已知限制（第一版）

  • 最多 6 盏灯（MAX_LIGHTS = 6）；默认仍是 Key/Fill/Rim 三盏（v0.8 多灯管理）。
  • 自定义灯具器械（v0.9）已支持「存当前灯为器械」+ JSON 导入/导出，但只存本地（localStorage），跨设备靠导出/导入手动搬运，见 V0_9_CUSTOM_FIXTURE_SPEC.md。
  • 多语言 UI（v1.0 起完整支持 中/英/日）：界面、内置数据派生标签和 A-B 文案全部三语化。新增文案用 src/i18n/* 的 useT()/t()，加 key 改 src/i18n/messages/<域>.ts、数据派生标签走 src/i18n/display.ts，不要把中文源串当 key，不要翻译用户输入/品牌/单位/id。见 V0_10_I18N_SPEC.md。
  • 桌面 / 封包工作台体验优先；移动端窄屏响应式后续单独排期。
  • 渲染为导演沟通向近似，非物理准确。

完整路线见 ROADMAP.md。

English

Direct Light is a white-studio lighting previz sandbox. To contribute:

  • No code required: use the Issue forms for reproducible bugs or visual feedback, and Discussions for lighting setups, production workflows, questions, and early ideas.
  • For code contributions, check open Issues. Discuss larger changes before implementation; small, focused bug fixes may go straight to a PR.
  • Requires Node.js >= 20.19.
  • npm install → npm run dev (Vite dev server on :5173).
  • Before any PR, make sure npx tsc -b, npm run lint, and npm run build all pass.
  • Read ARCHITECTURE.md for where code lives. Keep src/App.tsx thin; don't put logic back into the LightPanel / ObjectList / AppShell compatibility shells.
  • The renderer is a communication-oriented approximation, not a physically accurate simulation — prioritize readable, stable, real-time feedback. Rendering numbers live in src/data/rendering.ts.
  • Known limits: max 6 lights; multilingual UI (中/英/日) is complete as of v1.0.0; desktop-first. See ROADMAP.md and V0_10_I18N_SPEC.md.