Synvael/CONTRIBUTING.md

Contributing to Synvael

Thank you for your interest in contributing to Synvael. This document explains how contributions work, what is expected, and what contributors receive in return.

Philosophy

Synvael is open-source and commercially developed. The engine source code is licensed under AGPLv3, official game assets under CC-BY-NC-SA 4.0 (see LICENSE.md for full terms), and the project is built by Cryoforge Nexus, a commercial entity that intends to monetize the finished game.

Outside contributions are welcome and credited, but they do not carry equity or revenue share. If that trade does not work for you, please do not contribute. The project would rather be upfront about these terms than have anyone feel misled later.

Contributor Tiers

Core team

The core team makes architectural and roadmap decisions and is eligible for an ownership stake in Cryoforge Nexus, subject to the company's internal agreements.

Membership is not open by default, but there is a path in. A contributor becomes eligible for consideration when all of the following are met:

1. Sustained contribution. At least six months of active, merged contributions. Consistency and quality matter more than volume.
2. Architectural ownership. The contributor has taken responsibility for at least one subsystem (meshing, networking, worldgen, a major Lua API surface, etc.) and has demonstrated the ability to make sound design decisions within it, not just implement assigned tasks.
3. Community trust. A track record of constructive code reviews, issue discussions, and collaboration. No pattern of conflict or disregard for project norms.

When these criteria are met, an existing core member may nominate the contributor. Admission requires a supermajority vote (two-thirds or more) of current core members. The nominee may decline.

Meeting the criteria makes someone eligible for consideration, not entitled to membership. The final decision remains a human judgement about long-term fit with the team.

Outside contributors

Anyone who submits a pull request, asset, bug report, translation, or documentation change. Outside contributors receive public credit, authorship on their work under the project's open-source licenses, code review, mentorship where useful, and a voice in technical discussion. They do not receive equity, revenue share, or a guarantee of future paid work.

Contributor License Agreement (CLA)

Every contribution, code and assets alike, requires signing a Contributor License Agreement before a pull request can be merged. The CLA does not transfer copyright, contributors retain it. It grants Cryoforge Nexus a perpetual, irrevocable license to use, modify, sublicense, and relicense the contribution, including under commercial terms.

This is necessary because the public licenses (AGPLv3 + CC-BY-NC-SA 4.0) would otherwise prevent the planned monetization model. Without the CLA, contributed assets in particular would lock the project out of any commercial release.

How to sign

When a pull request is opened, an automated check verifies whether all commit authors have signed the CLA. If not, it posts a comment with instructions. To sign, leave a comment on the pull request containing:

I have read the CLA and I agree

The bot records the signature and updates the check status automatically. Signing is a one-time action; once recorded, all future pull requests from the same GitHub account are accepted without re-signing.

What is accepted

• Code in Rust (for engine crates) or Lua (for assets/scripts/ and mods/), licensed under AGPLv3.
• Original assets authored by the contributor: textures, models, sounds, icons, shaders. Licensed under CC-BY-NC-SA 4.0.
• Translations, documentation, bug reports, and design feedback.

What is not accepted

• Assets derived from copyrighted third-party material (other games, films, copyrighted art). All submitted assets must be original work.
• AI-generated assets. Textures, models, sounds, icons, and other non-code assets must be original human-authored work. See AI-Assisted Contributions below.
• Contributions without a signed CLA. The bot enforces this; unsigned pull requests cannot be merged.
• Native (Rust) mods submitted as pull requests. Native mods that link against engine internals are derivative works under AGPLv3 and belong in their own repositories. Lua mods are welcome in mods/.

Development Setup

Prerequisites

• Rust (stable toolchain, edition 2024)
• Git LFS (binary assets are tracked via LFS)
• A Vulkan-capable GPU with up-to-date drivers (Linux or Windows)

Building

git clone https://github.com/Cryoforge-Nexus/Synvael.git
cd Synvael
git lfs pull
cargo build

Running

cargo run -p client    # windowed client
cargo run -p server    # dedicated server

Testing

cargo test             # all tests
cargo test -p shared   # tests for a single crate

Linting

The CI pipeline enforces strict linting. Run these locally before pushing:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
selene .
stylua .

Lua linting requires Selene and StyLua. Install them via cargo install selene and cargo install stylua, or use the pre-built binaries from their release pages.

Coding Standards

All conventions, commit format, documentation style, naming, architecture boundaries and lint rules are documented in AGENTS.md. That file is the single source of truth; this section highlights the most relevant points for contributors.

Commit format

Conventional Commits with a mandatory crate-name scope:

<type>(<crate>): <imperative subject>

Types: feat, fix, refactor, perf, docs, test, chore, build, ci. Scope is the primary crate affected (client, server, renderer, shared, scripting) or workspace / assets for cross-cutting changes.

Examples:

feat(scripting): expose blocks.register to lua
fix(renderer): clamp swapchain extent to surface caps
docs(assets): document texture-pack overlay layout

Documentation

• Formal, objective tone. No first-person or second-person pronouns.
• Every public struct field requires a /// doc comment.
• Inline comments (//) above non-obvious logic.

Architecture boundaries

• Protocol/data types → shared
• Lua API and mlua integration → scripting
• GPU/draw code → renderer
• Input, windowing, presentation → client
• Simulation, authoritative logic → server

Do not place simulation logic in client. See AGENTS.md for the full rationale.

Pull Request Process

1. Branch from dev. The main branch is reserved for stable releases. All development happens on dev. For any feature of non-trivial scope, create a feature branch off dev (e.g., feat/new-worldgen).
2. One concept per pull request. Keep changes focused. If a pull request touches multiple unrelated systems, split it.
3. Ensure CI passes. The pipeline runs cargo fmt, cargo clippy, selene, and stylua. Pull requests with lint failures are not reviewed.
4. Sign the CLA. The CLA bot must report a passing status before review begins.
5. Describe the change. Explain what the pull request does, why it is needed, and any design decisions made. Link to relevant issues if applicable.
6. Respond to review feedback. Maintainers may request changes. Please address them or discuss alternatives.

Recognition

Every merged contribution earns an entry in CREDITS.md. Substantial or sustained contributions are highlighted on the project website. Standout contributors may, once the project has revenue, be offered paid bounties for specific scoped work, this is a transactional arrangement, not equity or an ongoing revenue share.

This is the honest ceiling of what outside contribution earns. If the goal is co-ownership of a game studio, this project is not the right fit.

AI-Assisted Contributions

AI tools (code completion, generation, refactoring assistants) may be used as aids when writing code. The following rules apply:

• AI-assisted code is accepted, with conditions. The contributor must have genuinely reviewed every line of the submitted code and be able to explain what it does and why. Contributions where the author cannot answer questions about their own code during review will be rejected. The contributor, not the AI tool, is the responsible author.
• AI-generated assets are not accepted. Textures, models, sounds, icons, and other non-code assets must be original human-authored work. This applies regardless of the AI tool or its training-data provenance.
• Disclosure is required. If AI tools were used in a material way during the creation of a code contribution, this must be stated in the pull request description. A brief note (e.g., "AI-assisted: used Copilot for boilerplate generation") is sufficient.

Questions?

Open an issue or start a discussion on the repository. Maintainers are happy to help with setup, answer questions about the architecture, or discuss proposed changes before work begins.