# Contributing to EffectCraft

Thanks for helping. Please read [AGENTS.md](AGENTS.md) first: its rules on assets and clean-room
work apply to everyone, people and AI agents alike, and they are not negotiable.

## Setup

You need [Rust](https://rustup.rs/) 1.95 or newer.

```sh
cargo run -p effectcraft -- --demo       # the desktop app, with the demo project
cargo test --workspace
cargo xtask ci                           # what every commit must pass
```

### Windows

The MSVC toolchain, rustup's default on Windows, is what the releases use: with the Visual Studio
C++ build tools installed, the commands above work as they are.

The GNU toolchain (`x86_64-pc-windows-gnu`) needs a current mingw-w64 GCC and binutils first on
`PATH`. They provide the linker and the Windows import libraries, such as `libshlwapi.a` for
opening links from the app. With [MSYS2](https://www.msys2.org/):

```powershell
C:\msys64\usr\bin\pacman.exe -S --needed mingw-w64-x86_64-gcc
$env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
cargo +stable-x86_64-pc-windows-gnu run -p effectcraft -- --demo
```

An older MinGW earlier on `PATH` can break the build: CodeBlocks' GCC 8.1 fails to link
`boa_engine` ([#1882](https://github.com/storytold/effectcraft/issues/1882)).

Rust's bundled LLD and self-contained libraries don't include every import library EffectCraft
needs, so on their own they stop with `unable to find library -lshlwapi`
([#1886](https://github.com/storytold/effectcraft/issues/1886)). To link that way, add mingw-w64's
libraries to the search path in your own Cargo config (`%USERPROFILE%\.cargo\config.toml`):

```toml
[target.x86_64-pc-windows-gnu]
linker = "rust-lld"
rustflags = ["-C", "link-self-contained=yes", "-L", "native=C:/msys64/mingw64/lib"]
```

The `Windows toolchains` workflow builds the app and the CLI each of these three ways every night.

## Ground rules

- **Clean room.** Work from After Effects' public documentation and its observable behaviour only.
  Never use Adobe artwork, presets or code, and never copy GPL/LGPL/AGPL code.
- **Every asset is attributed.** Add a `.attribution` sidecar and an [ATTRIBUTION.md](ATTRIBUTION.md)
  row; `cargo xtask assets` checks it.
- **Layering.** Nothing below the interface layer depends on UI or OS crates; see
  [docs/architecture.md](docs/architecture.md).
- **Everything is a command.** New features are engine commands with an id, label, menu path,
  shortcut and parameters, so the UI, the CLI and the MCP server get them at once. Interactive
  widgets register an automation id.
- **Never crash.** Non-test code returns errors instead of panicking: no `unwrap()`, `expect()`,
  `panic!`, `unreachable!`, `todo!`, `unimplemented!` or `unsafe`, checked indexing and arithmetic on
  input-derived values, and a regression test with every crash fix. See the "Never crash" section of
  [AGENTS.md](AGENTS.md).
- **Tests with every change**, and green `cargo xtask ci` before every commit. One task per commit.

## How to add…

- **An effect:** add an `EffectSpec` in `crates/effects` (AE display name, category, parameters
  with AE's names, defaults and ranges) and its render function, with a determinism test and a
  behaviour test. If it reads the clock directly, add it to `TIME_DEPENDENT`.
- **A command:** register it with `cmd!` in `crates/engine/src/commands/`, place it in the menu
  tree in `crates/engine/src/menus.rs`, and test it including undo.
- **A panel or dialog:** `crates/ui-egui/src/panels/`; look at the result with the headless
  snapshot tool described in [docs/testing.md](docs/testing.md).

## Talk to us

Questions, ideas and bug reports are welcome on [Discord](https://discord.gg/artcraft) and in
GitHub issues.