Contributing

If you want to help us improve Eternaltwin, this document will help you find your way.

This section focuses on the eternaltwin repository, which holds the main Eternaltwin server and the code used to link other projects to it:

User accounts: registration, sign-in, profiles, and the links between an Eternaltwin account and external accounts (Discord, GitLab, and the archived Motion Twin profiles). Registration and sign-in are guarded by a proof-of-work captcha.
OAuth provider: games and third-party sites authenticate their players through Eternaltwin. See OAuth and Application development.
Forums (or "fora"): sections, threads, posts, roles and moderation, with Marktwin as the markup language. See Forum.
Archives for the official Motion Twin websites: Hammerfest, Dinoparc and Twinoid data, stored with its full history and exposed through the API. See Archive for how it is built, and Archive for the data model.

If you wish to help with a specific game, you should contact the dedicated group on Discord.

Requirements

Tool	Version	Pinned in
Rust	`>= 1.89.0`	`rust-version` in the workspace `Cargo.toml` (edition `2024`)
Node.js	`>= 20.11.0`	`engines.node` in the root `package.json`
Yarn	`4.12.0` exactly	`yarnPath` in `.yarnrc.yml`, `packageManager` in `package.json`
Postgres	optional in dev	see below

Yarn is Yarn Berry (Yarn 4), committed to the repository under .yarn/releases/. Do not install it with npm install --global yarn: that installs the legacy Yarn 1 line. Enable Corepack instead, as described on the Yarn page.

Postgres is not required to start a development server: the development profile defaults to backend.store = "Memory", so every store lives in RAM and the data is lost on restart. You need Postgres as soon as you want data to survive a restart, or when you work on the SQL schema or on a Pg* store. Read Database to set up a cluster, a role and a database. The production server runs Postgres 17.2, see Server.

Getting started

git clone git@gitlab.com:eternaltwin/eternaltwin.git
cd eternaltwin
yarn install

The development setup is two processes. Start them in two terminals, from the repository root:

yarn run start:dev:back

yarn run start:dev:front

start:dev:back runs cargo run --bin eternaltwin backend. The backend serves the REST API (/api/v1), the OAuth endpoints and the form action handlers on port 50320.
start:dev:front runs the Angular development server in packages/website, on port 4200 by default. It proxies /api/v1, /oauth and /actions to the backend, as configured in packages/website/proxy.conf.json.

The first backend build compiles the whole Rust workspace and takes a while.

Configuration

The server reads its configuration from the first matching file in the working directory, in this order: eternaltwin.<profile>.local.toml, eternaltwin.<profile>.local.json, eternaltwin.<profile>.toml, eternaltwin.<profile>.json, eternaltwin.local.toml, eternaltwin.local.json, eternaltwin.toml, eternaltwin.json. The profile is dev unless told otherwise.

If no file is found, the built-in defaults for the profile apply, which is why the backend starts without any configuration at all. eternaltwin.local.toml is ignored by Git, so it is the usual place for your own settings; the committed eternaltwin.test.toml is a commented reference of every section. The settings are defined in crates/config.

Tests

yarn run test

This builds the TypeScript test files and the packages/exe binary wrapper, then runs the Node test runner over packages/*/test/**/*.spec.mjs and sdk/node/*/test/**/*.spec.mjs.

The Rust tests run with cargo test. Tests for the Pg* stores need a Postgres database configured through [postgres]; the memory stores are tested without one.

The database helper scripts are yarn run db:check, yarn run db:reset and yarn run db:sync; each one forwards to eternaltwin db <subcommand>.

Style

yarn run lint

lint runs ESLint over packages/*/src/**/*.mts; yarn run format is the same check with --fix. The Rust side uses cargo fmt --all and cargo clippy --all-targets --all-features -- -D warnings, configured by rustfmt.toml and clippy.toml.

In this section

Overview: the layout of the repository, package by package.
Publish: how to cut a release and publish it.
Archive: how the archive of the Motion Twin websites is organized.