Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (66 loc) · 7.56 KB

CONTRIBUTING.md

File metadata and controls

98 lines (66 loc) · 7.56 KB
Raw

Contributing to Donify

Contributions to flight behavior, audio, cockpit interaction, environments, installation and documentation are welcome. Keep each change focused on a concrete problem and include evidence needed to review the result. English and French issue reports and pull requests are welcome.

Start with Getting started and the architecture guide. The detailed French flight guide explains the intended control behavior.

Development setup

The supported development path is Linux, Unreal Engine 5.8.1, and Vulkan. Install the engine with its Linux toolchain, Git, Bash, Python 3 and rg (ripgrep). From the repository root:

export DONIFY_ENGINE_DIR="/path/to/UnrealEngine5.8"
python3 Scripts/assets.py fetch
python3 Scripts/check_architecture.py
./Scripts/build.sh
./Scripts/launch.sh

Use ./Scripts/editor.sh to open the editor. New materials may require shader compilation. Launching the game does not rebuild changed C++ sources automatically.

Runtime assets are fetched separately from source. Generating or importing resources may require additional tools; it is not part of an ordinary C++ build. Contributors do not need asset-storage credentials or a generative service API key to run prepared runtime assets. Never commit .env, credentials, personal logs, or local build outputs.

The release runtime pack includes the twelve reference houses with indoor passages and their updated collisions. For an existing installation, follow the upgrade instructions. Regeneration and import are only needed when editing the house assets; the indoor flight guide documents those optional authoring steps.

Pick the right module

Change Start here
Force, torque, units, battery or controller math Source/DonifySimulation/Private/DroneDynamics.cpp and its public contract
Deterministic physics regression Source/DonifySimulation/Private/DroneDynamicsChecks.cpp
Sound behavior, mixing or announcements Source/DonifyAudio/; extend FDonifyAudioState explicitly if another measurement is needed
Input mapping or command behavior Config/DefaultInput.ini, Source/Donify/Flight/ControlInput.cpp, and input display
Flight assistance, missions or scene contacts Source/Donify/Flight/FlightControl.cpp
Cockpit or map Source/Donify/UI/FlightHUD.cpp or CockpitMap.cpp
Environment or visible drone Source/Donify/World/ or Source/Donify/Presentation/
Reproducible game scenarios Source/Donify/Diagnostics/

The complete feature map explains ownership and remaining coupling. Keep these boundaries explicit:

  • DonifySimulation depends on Unreal Core, without actors, HUD, audio or /Game resources.
  • DonifyAudio receives a read-only flight snapshot and must not include the pawn, HUD or world classes.
  • Donify owns integration with the engine scene. Include the specific header needed, such as Flight/DronePawn.h, instead of the compatibility umbrella Donify.h.
  • Declare dependencies in each module's *.Build.cs and use public interfaces. Do not reach into another module's Private/ directory.

Document physical units and reference frames. Dynamics uses SI units; scene positions, collisions, routes and flight trails use centimeters. World altitude targets differ from measured clearance above a support. Preserve the fixed 1/240-second physics step when changing presentation or audio updates.

Prefer a local, readable change to unrelated reformatting. Explain the reason for a calculation or invariant when the code alone cannot convey it.

Verify the change

After a C++ change, build before running the game checks:

python3 Scripts/check_architecture.py
./Scripts/build.sh
./Scripts/check.sh

check.sh also runs the architecture check, launches the game and requires 23 markers in Saved/Logs/Validation.log. The physics marker aggregates 13 dynamics checks; the other 22 markers cover integration behavior, including six indoor scenarios. A missing marker or FAIL fails the command. See the public release validation, development validation history, and source assertions for the exact scope.

Change Useful evidence
Dynamics, input or assistance Run the game suite and add a regression that reproduces the defect or checks the new invariant
Audio behavior Run the suite, then listen to the audio probe if the output sound changes
Cockpit, map or controller drawing Capture the result, inspect another resolution, and exercise affected controls
Buildings, terrain or vegetation Inspect the import report, appearance, scale and affected collisions
Documentation only Check changed links, file names and commands; a new flight test is unnecessary

Capture the cockpit and a smaller window with details visible:

./Scripts/launch.sh -DonifyCapture -DonifyShot=9 -DonifyCaptureName=Contribution-cockpit.png
./Scripts/launch.sh -DonifyCapture -DonifyShot=9 -DonifyHUDDetails -ResX=1280 -ResY=800

These prepared capture sessions wait for shaders, save an image and exit. They are silent, like the validation runner. A capture fixture does not replace testing an interaction. To listen to a short diagnostic flight:

./Scripts/launch.sh -DonifyAudioProbe -DonifyShot=9

An audio-state assertion cannot establish the audible volume of a physical output device. Do not loosen physical tolerances simply to make a regression pass: explain a model change and update its assumptions in FlightPhysics.md.

Asset contributions

Keep the connection between a source, its preparation script, and the imported Unreal resource. Describe provenance, reuse conditions, import units and reproduction parameters. Check THIRD_PARTY_NOTICES.md before adding or redistributing resources; a source-code license does not automatically cover assets.

Large binaries are kept outside the source repository. Do not add runtime or source asset binaries directly to a pull request. Provide the proposed manifest change, provenance and reproduction steps so a maintainer can review and publish a versioned bundle. A C++ change does not require regenerating assets.

Existing guides cover audio, textures, PBR materials, models, and world scale. Optional generation services may consume credits; regenerate only resources needed for your change.

Issues and pull requests

For a bug report, include the engine version, OS, GPU, reproduction steps, expected and actual behavior, and the relevant error excerpt. Remove usernames, personal paths and secrets from attached logs. A short video or screenshot helps with visual or input problems.

Fork the repository, create a focused branch, and open a pull request. Explain the problem and resulting behavior, list the modules changed, and report checks actually run with their results. State what remains unverified. Include a screenshot for rendering changes and measured values for flight-model changes.

Update the controls guide when bindings or behavior change, and architecture documentation when a responsibility or interface moves. By submitting a contribution, you agree to make your original contribution available under the project's MIT License; identify any separately licensed material explicitly.