Skip to content

Latest commit

 

History

History
242 lines (160 loc) · 9.15 KB

CONTRIBUTING.md

File metadata and controls

242 lines (160 loc) · 9.15 KB
Raw

Contributing to Digital Extinction

Suggesting Changes

  1. Start an informal discussions.
  2. Open a formal issue.

First Time Contributions

Making Changes

  1. First, discuss any non-trivial or potentially controversial changes in our Discussions.

    You can skip this step if you are basing you changes on an already concluded discussion or an issue.

  2. Currently, the surface area of the game is still relatively small. To avoid duplicate work while working on non-trivial changes, please mention your intention to do the work in the appropriate issue.

    You may consult Indy's Backlog to see what he intends to work on in the near future.

  3. Implement the changes. Do not forget to include appropriate unit tests and, when possible, thoroughly test you changes manually.

  4. Open a pull request (PR).

  5. @Indy2222 and the community review the PR. During the review process, the PR might be accepted right away, changes might be requested or it might be rejected.

Pull Requests & Git

  • Try to split your work into separate and atomic commits. Put any non-obvious reasoning behind any change to the commit description. Separate “preparatory” changes and modifications from new features & improvements. Hide the sausage making.

  • Do not push any binary files larger than 32KiB directly to the repository, use Git LFS instead. For consistency reasons, you may track even smaller binary files with Git LFS.

  • Link relevant issues from your commits.

Development Process

  • main branch is considered stable. In theory, it should be possible to release a new version from the branch at any time.

  • The development process is incremental. There are no final or big versions.

  • Release train: after version 0.1 is released, a new version is released every 6 weeks.

Coding Style

  • We are limiting the amount of unsafe code to the very minimum. The same principle applies to complex architecture or code patterns.

    A lot of the ergonomy and performance gains unlocked by unsafe or complex code are already delivered by Bevy and its API.

  • Rustfmt configured by rustfmt.toml is used for Rust code formatting. Note that nightly version of the tool is required.

  • Maximum line length of Markdown files is 79 characters.

  • Keep individual Bevy system complexity and the number of its parameters low. When the complexity grows, split the system and use events for inter-system communication.

  • SystemSet enum names end with Set (for example CameraSet). Event struct names end with Event (for example DoubleClickEvent).

Crate Structure

  • Each crate is small (several thousand SLOC or less), simple and self-contained.

  • The public API of each crate is small or empty.

  • Each "Bevy" based crate implements a PluginGroup placed in lib.rs.

  • The crate is split into one or more individual Plugins. Each is placed to a separate module.

  • Systems are (usually) located alongside their respective plugins.

  • Inter-crate interaction leans heavily on the usage of Bevy events.

  • All components and resources exposed in a crate public API, must be inserted, removed and modified only from their respective crate.

Getting Oriented

Rust documentation is automatically build and deployed from main branch to docs.de-game.org.

The game is split into multiple crates, each implementing part of the game logic. This repository contains a Cargo workspace which consists of all the sub-crates. The crate inter-dependencies form an orderly DAG.

Topologically sorted crates:

  • de_lobby – lobby server.

  • de_uom – type safe units of measurements.

  • core – various simple core utilities, structs, and so on. These are used across many different crates.

  • map – map (de)serialization, validation and representation functionalities.

  • menu – game menu and related functionality.

  • terrain – functionality related to game terrain.

  • objects – caching of object on the game map.

  • index – spatial index of all solid entities in the game.

  • signs – various world space UI signs in Digital Extinction. For example health bars, arrows, and so on.

  • spawner – object spawning, drafting and construction.

  • camera

  • loader – map loading logic.

  • pathing – global path finding and path (re)scheduling.

  • movement – entity movement, local dynamic obstacle avoidance, kinematics and similar.

  • behaviour – unit level behaviour and AI.

  • combat – attacking, projectile & laser simulation and similar.

  • controller – handling of user input and containing head-up display with 2D in-game UI.

Repository Structure

  • /assets — all game assets are located here. These are distributed together with the game executable.

  • /crates — the game comprises many small crates in a single workspace, all of them except the main crate (de_game) are located in this directory.

    Each sub-directory contains sources of a crate whose name is the same as the name of its directory plus the de_ prefix.

  • /projects — project files (e.g. Blender .blend files) used during creation of the assets.

  • /docs — technical documentation of the game. The documentation is automatically extended with Rust docs and deployed to docs.de-game.org from the main branch.

  • /src — source code of the main crate (de_game). All of the game functionality is broken down into separate crates. The purpose of the main crate is to put everything together via Bevy's plugin groups, thus its source code is very compact.

  • /utils — various utilities (e.g. small Python scripts) intended for contributors.

Bevy Schedule

See de_core::baseset::GameSet.

Coordinate Systems

3D XYZ world coordinates are right handed. Mean sea level (MSL) plane lies on XZ axes. Y axis points upwards.

2D map coordinates X (longitude) Y (latitude) map to 3D world coordinates X and -Z respectively. Always use module de_core::projection for projection onto MSL plane or conversion between 3D world coordinates and 2D map coordinates.

Geometry & Linear Algebra

Glam is used as the primary linear algebra crate.

Parry is used for collision detection and geometry. Parry is using Nalgebra for linear algebra, thus Nalgebra is used in various places where usage of Glam would lead to frequent back and forth conversions.

Contributing Assets

3D Models

  • See the A-Models issue label to filter issues related to the 3D models.

  • 3D models (buildings, units, map elements, etc.) are located in /assets/models.

  • 3D models need to be exported into glTF 2.0 format.

  • Whenever applicable and desirable by the author, add the original 3D modeling project file (e.g. .blend file from Blender) to /projects/ directory.

  • The +Y axis points upwards, and the front of the model points in the +X direction.

  • The ground consists of the XZ plane (Y = 0) and is located just below the model. Foundations of buildings may go below the ground plane to allow construction on uneven terrain. The altitude of flying units is controlled independently of the model, thus even flying objects should be just above the ground plane (and not higher).

  • Whenever applicable, models are centered in the XZ axes. I.e. axis-aligned bounding box (AABB) of the model has its center at (X=0, Y=?, Z=0).