Building and contributing

Running the app

You need Node.js 20.19 or newer.

git clone https://github.com/SpaceEngineerSS/PhotonLab.git
cd PhotonLab
npm install
npm run dev          # the app on http://localhost:5173
npm run dev:docs     # this site on http://localhost:4321/docs

The compiled solver is committed in rust-core/pkg, so you do not need Rust to work on the interface or the documentation.

Rebuilding the solver

Install Rust with the WebAssembly target and wasm-pack:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

Then:

npm run build:wasm                     # rebuilds rust-core/pkg
cd rust-core && cargo test --release   # physics tests

build:wasm enables WebAssembly SIMD (rust-core/.cargo/config.toml) and removes the files wasm-pack generates that do not belong in the repository. Commit the updated pkg/ together with your Rust changes; CI checks that the bindings match the sources.

cargo run --release --example bench prints the cost of a time step on your machine.

Checks

npm run lint
npm run typecheck
npm test               # web unit tests
npm run build          # app + docs, exactly as deployed

CI runs all of these plus cargo fmt --check, cargo clippy -D warnings and the Rust tests.

Screenshots and figures

The images in this documentation are generated, not drawn by hand:

node tools/assets/diagrams.mjs   # the SVG figures, in both languages
npm run dev                      # then, in another terminal:
node tools/capture/capture.mjs   # screenshots from the running app
node tools/assets/make-icons.mjs # app icons

If you change the interface, regenerate the screenshots so the docs stay honest.

Sending changes

Bug reports and pull requests are welcome. For anything larger than a fix, open an issue first so we can agree on the approach. Keep pull requests focused, include a test where it makes sense, and describe what you checked by hand. For physics changes, include the validation numbers before and after.

The full guidelines are in CONTRIBUTING.md.