The system relies on a shared C ABI defined in particle_core to allow different languages to interact without using dlopen between packages.

The Core Interface

particle_core provides:

• Two vtable types: pc_emitter_vtable_t and pc_modifier_vtable_t.
• A runtime pc_pool_t that manages particles, runs modifiers, and pulls from emitters.

Cross-Language Flow

1. Implementation: particle_cpp and particle_rs implement the vtable interfaces and export discovery functions (e.g., particle_cpp_get_emitter("cone")).
2. Python Bindings: particle_cpp_py (via pybind11) and particle_rs (via PyO3) expose these implementations as Python objects. These objects expose vtable_addr and state_addr as integers.
3. Execution: The particle_view module (a pybind11 module) provides a View(w, h).run(emitters=[...], modifiers=[...]) function. It accepts the raw integer addresses provided by the Python objects, builds a pc_pool_t internally, and executes the SDL loop.
4. Orchestration: particle_kit acts as the high-level orchestrator, importing the binding modules and the view to build and run scenes.

To avoid repeating configuration for multiple platforms that share common traits, you can use the * wildcard in a target selector. This is most effective when using custom platform names in your workspace.platforms definition.

Rules for Wildcards:

• * is the only supported metacharacter and matches any run of characters.
• Patterns are matched in full and are case-sensitive (e.g., cuda-*, *-64, *cuda*).
• Precedence: If multiple selectors match a platform, the one defined later in the pixi.toml manifest wins. Always place specific overrides (e.g., [target.cuda-win-64]) after the wildcard block (e.g., [target."cuda-*"]).
• Restrictions: Wildcards are only allowed on workspace and feature targets. They are not supported in [package.target] or [package.build.target].

[workspace]
platforms = [
  { name = "cuda-win-64", platform = "win-64", cuda = "12" },
  { name = "cuda-linux-64", platform = "linux-64", cuda = "12" },
  "win-64",
  "linux-64",
]

[target."cuda-*".tasks]
test = "python test.py --cuda"
train = "python train.py --cuda"

Pixi follows a strict hierarchy when resolving environment variables. If a variable is defined at multiple levels, the level with the highest priority wins.

Priority Order (Highest to Lowest):

1. task.env (Defined in [tasks.<name>.env] in pixi.toml)
2. activation.env (Defined in [activation.env] in pixi.toml)
3. activation.scripts (Variables exported in files listed in [activation.scripts])
4. Activation scripts of dependencies
5. Outside environment variables (Variables set in your shell/system before running Pixi)

Example: task.env overriding everything

If you define APP_CONFIG in a task, it will override values in activation settings, dependencies, and your system shell.

[tasks.start]
cmd = "echo Config: $APP_CONFIG"
env = { APP_CONFIG = "task-specific" }

[activation.env]
APP_CONFIG = "activation-env"

[activation]
scripts = ["app_setup.sh"]

[dependencies]
config-loader = "*"  # Sets APP_CONFIG="dependency-config"

export APP_CONFIG="activation-script"

If you run pixi run start while export APP_CONFIG="system-config" is set in your shell, the output will be: Config: task-specific

[tasks.start]
cmd = "echo Config: $APP_CONFIG"
env = { APP_CONFIG = "task-specific" }

[activation.env]
APP_CONFIG = "activation-env"

[activation]
scripts = ["app_setup.sh"]

[dependencies]
config-loader = "*"  # Sets APP_CONFIG="dependency-config"

export APP_CONFIG="activation-script"

Running the command:

pixi run start

Output: Config: task-specific

The [constraints] table allows you to restrict the versions of packages that may be installed without explicitly requiring them as dependencies. A constraint is only enforced if the package is pulled in by another dependency.

This is useful for:

• Preventing known-bad versions: Ruling out a specific version range of a transitive dependency that has a regression.
• Coordinating optional packages: Ensuring that if an optional library (like CUDA) is installed, it meets a specific version requirement.

Constraints use the same VersionSpec and MatchSpec syntax as [dependencies]. They can also be made platform-specific using the [target.<platform>.constraints] table.

[dependencies]
requests = ">=2.28"

[constraints]
# Ensures openssl is at least 3.0 if it is pulled in transitively
openssl = ">=3.0"

[target.linux-64.constraints]
# Tighten the constraint specifically for Linux
openssl = ">=3.0.7"

You can use Pixi solve-groups to ensure that different environments (e.g., default for development and prod for production) use identical dependency versions while allowing different installation modes.

Specifically, you can use the editable flag in pypi-dependencies to install a local package as editable in development environments for faster iteration, while installing it as non-editable in production environments for a clean deployment. This is achieved by defining different features for each environment and assigning them to the same solve-group.

[tool.pixi.feature.dev.pypi-dependencies]
docker-project = { path = ".", editable = true }

[tool.pixi.feature.prod.pypi-dependencies]
docker-project = { path = ".", editable = false }

[tool.pixi.environments]
default = { features = ["test", "dev"], solve-group = "default" }
prod = { features = ["prod"], solve-group = "default" }

Be aware that package installation and activation can trigger arbitrary code execution:

• post-link scripts: These run during installation. Pixi disables these by default. Do not enable them unless you have explicitly reviewed the package behavior.
• Activation scripts: These run during environment activation (e.g., when using pixi shell, pixi run, or pixi shell-hook). These are enabled by default as part of standard conda behavior.
• Resolution-time execution: Commands like pixi lock, pixi install, and pixi update can execute code if your project contains source dependencies, as Pixi must invoke the package's build backend. Only run these commands on trusted projects or within a sandbox.

Security Tip for direnv users: If you use watch_file pixi.lock, a change to the lock file will automatically trigger pixi shell-hook, which can execute malicious activation scripts. Consider using require_allowed pixi.toml pixi.lock (once supported by direnv) to force a manual approval step.