Introduction

Alloy is an experimental game engine written in Rust which aims to recreate logic previously authored in my C++ engine of the same name.

In particular, this project exists to explore working with Graphics, Audio, and all of the fun linear algebra required for rendering.

Project Goals

The goals of this project are:

Abstracting the underlying rendering system: The user should not have to care if they are using OpenGL, Vulkan, or DirectX; but this should also be selectable on-the-fly. Shaders should be pre-compiled where possible, and internalized as high-level Material objects.
Abstracting the underlying audio system: Same as above; the user should not have to care if they are using OpenAL or FMOD; but this should also be selectable on-the-fly.
Support for both 2 and 3 rendering: The ultimate goal is actually to do 2.5-D renderings, where the world is "3D", but appears as 2D pixel-art. However, the engine should adapt to both.
Model scene graphs: Models should be able to be composed of multiple bones, which can be rendered via scene-graphs and handle bone logic.

Tour of Alloy-rs

These subpages will provide a small tour of the functionality available in the alloy-rs engine and supporting development kit.

Engine
Editors

Tour of the Alloy Engine

Note

Many of these sections are "forward-thinking" as these are still in-progress unless otherwise specified.

This is a tour of the Alloy Engine's software integration. This section will provide detailed instructions to set up and prepare an Alloy application.

Setting up an Application

🚧 This article is a work in progress.

Building a Game Loop

🚧 This article is a work in progress.

Rendering

🚧 This article is a work in progress.

Tour of the Editors

Note

Many of these sections are "forward-thinking" as these are still in-progress unless otherwise specified.

This section provides a tour of the different editors that are available within Alloy.

Material Editor

🚧 This article is a work in progress.

Localization Editor

🚧 This article is a work in progress.

Tileset Manager

🚧 This article is a work in progress.

Resource Pipeline

🚧 This article is a work in progress.

Storage Formats

🚧 This article is a work in progress.

Additional Resources

Below are some additional useful resources and links for working with Alloy. This includes the general docs for this project, as well as docs for libraries used in the implementation of this project.

Development

These subpages are mainly important for contributors, and will define parts of the development process and requirements in this project.

Commit Standards

The Alloy project has some some requirements on how git commit messages are formed.

General

Commits should be small, granular, and easy to follow and revert. Ideally, the same SOC practices that would be applied to software development should be applied to commits; each commit identifies a separtion of concerns.

Commit Titles

must be in imperitive, present-tense
must be no longer than 50 characters
must be prefixed by an emoji key to indicate what the change is, followed by a space
- If a commit may use more than one emoji to identify the change, it might indicate that the change is not granular enough, and you may be a candidate to be broken down into smaller commits for easier consumption

Commit Messages

Must not exceed 72-character wide
- Exceptions are made if a message contains a link or other figure that exceeds the 72 character rule by nature
Must indicate the rationale for the change, what was changed, and why
- In general, more details are always better to help identify the cause of changes in a repository

Emoji Key

Emojis are used to prefix commit titles in order to simplify categorization of git log messages.

Use the table below to identify which prefixes should be used for the respective change:

Emoji	Reason
🔖	Version Tag
📖	Documentation / Textual Changes
📇	Metadata (README, LICENSE, repo docs, etc)
🚦	Continuous Integration
✨	New Feature
✏	Rename
🔨	Refactor
⚠️	Deprecation
🗑️	Removal
🎨	Cosmetic
🩹	Bug fix
🧹	Code Cleanup (includes moving types/files around)
⏱	Tuning / Performance
🎯	Testing (unit, benchmark, integration, etc)
🔧	Tooling
🔐	Security
♿	Accessibility
🌐	Localization / Internationalization
🚧	WIP

Note: This list may be incomplete, and not cover all possible areas that would be needed. Please feel free to start a discussion if new tags would be more appropriate. Similarly, if there are more appropriate emojis to use as tags, feel free to provide suggestions!

Identifying Release-impacting Changes

Rather than misusing git through the likes of "conventional commits" or some other equivalent, Alloy uses git trailers to identify changes that impact different change categories. Specifically, commits may contain the following trailer(s) which will influence release generation:

Change-Category: -- Indicates the type of change being made. May be one of feature, fix/bugfix. Optionally supports the word breaking (*) to indicate a deviation from currently promised behavior.
System: -- Identifies the affected system (optional). When specified, is free-form -- but messages will be grouped together in the release notes to identify this.

When related to a ticket, trailers may also contain Fixes:, Closes:, or any of the GitHub trailers.

What constitutes a breaking change

Note: This project is far from being ready for a "breaking" change as it is pre-1.0, so this section is forward-thinking.

A "breaking change" for Alloy is defined as something that, either knowingly or unknowingly, changes software behavior from the perspective of the game engine itself. This dstinction is important, as it means that a change in behavior is not enough to constitute a "breaking" change, if the change is aligning behavior with what the expectation should be.

For example, if Alloy declares the behavior of a function to do a specific thing, and it does not properly achieve the documented behavior -- then fixing this behavior will only be considered a bug fix and not a breaking change. Users who rely on the consequence of a bug will suffer breakages, but that is by design.

If, on the other hand, the change were to change documented behavior -- this will fall into the category of a "breaking change", since it deviates from existing behavior.

Branch Strategy

Development

Since this project is a sole-authorship, the current branching strategy is to leverage the develop branch for active development, and to use a companion GitHub workflow that will automatically verify and promote these changes back to master provided that they build and test correctly. Promotion is done via fast-forwarding to preserve signed git commits.

In some cases, larger features will be developed as separate branches so that the changes can be included and identified by the totality of the branch, rather than by scanning individual commits.

Releases

The strategy for creating releases is to first create a release/{version} branch where work that is dedicated to a release will be pushed to, following a similar strategy as for normal development. The branch name identifies the major.minor semantic version, but not the patch. Both the patch version and release-candidates will be identified in annotated tags and GitHub releases.

Work identified for the release will be made onto this branch, and will merge back into develop and promoted to master to keep the two branches synchronized.

---
title: Release branching
---
%%{init: { 'gitGraph': {'mainBranchName': 'develop'}} }%%
gitGraph
  commit
  commit
  branch release/v1.3
  commit
  checkout develop
  commit
  checkout release/v1.3
  commit tag: "v1.3.0-rc-0"
  checkout develop
  merge release/v1.3
  commit
  checkout release/v1.3
  commit tag: "v1.3.0"
  checkout develop
  merge release/v1.3

Once a final non release-candidate build is decided, an annotated tag and GitHub release will be created marking the vX.Y.0 version. At this point, the release branch is left only for patch fixes/bug-fixes, but will no longer be merged back in to develop as it is no longer the actively maintained branch.

Hotfixes and Patches

Patches will NOT use the cherry-pick strategy, as this causes duplicate commits with the same content when merging release branches back into develop/master. Instead, to keep branches up-to-date and to accurately reflect the state of fixes, a new branch created at the common ancestor of the affected release branch(es) will be created. This branch will be merged into the afflicted release branches with a normal merge strategy, resolving any conflicts in the merge commit.

If there is an active release branch for which a non release-candidate has been created, the normal process outlined above is followed, where the release branch will merge back in to develop and continue as normal. If there is no active release branch, the fix will be merged into develop directly.

---
title: Fixing multiple branches
---
%%{init: { 'gitGraph': {'mainBranchName': 'develop'}} }%%
gitGraph
  checkout develop
  commit
  branch release/v1.2
  branch hotfix
  checkout release/v1.2
  commit
  commit
  commit tag: "v1.2.0-rc0"
  checkout develop
  checkout release/v1.2
  commit tag: "v1.2.0"
  checkout develop
  merge release/v1.2
  commit
  commit
  commit
  branch release/v1.3
  commit
  commit
  commit tag: "v1.3.0-rc0"
  checkout hotfix
  commit
  checkout release/v1.3
  merge hotfix tag: "v1.3.0-rc1"
  commit tag: "v1.3.0"
  checkout develop
  merge release/v1.3
  checkout hotfix
  checkout release/v1.2
  merge hotfix tag: "v1.2.1"

Using this strategy allows the SHA1 of the initial fix to be checked against the release branch to verify that the fix has indeed been introduced into previous releases. The standard cherry-pick method does not allow for this, and often introduces divergent code when conflicts arise; leading to release branches with no real guarantee of correctness.

Definition of Done

This outlines the basic checklist of requirements to state that a task has been "completed".

Checklist

The change has been tested by CI and passes all failing tests
If the change introduced new code, the new code has been tested
If the change is fixing a bug in old code, the bug has been recreated in a unit test and has been verified

Legal

This development kit is dual-licensed under both the MIT License and the Apache-2 License which are both open-source initiative approved license.

Under this license, you may use Alloy for any purpose you wish WITHOUT ANY WARRANTY, and modify it as you see fit -- subject to the one condition that the license is preserved.

Contributing

All contributions made to this project implicitly agree to dual-licensed the contributions to this project, under the MIT License and the Apache-2 License.

Endorsement

At no point is Alloy or any of its contributors to be misrepresented as endorsing a project that uses this engine without prior written acknowledgement from the maintainers.

List of 3rd-Party Licenses

This project keeps a record of all 3rd-party licenses used by this project and implicit third-parties. This list can be found below:

List of 3rd-Party Licenses

Community

Note

This community section aggregates the same community-contribution files that can be found from within the GitHub UI.

Contribution Guidelines

Thank you for your interest in this project! I sincerely appreciate your enthusiasm and eagerness to contribute, as public contributions are fundamental to the open-source community.

However, at this moment, I am not actively accepting external contributions. This project primarily exists to experiment and learn about game engine design in Rust -- and as such has a much looser focus and roadmap that is currently aligned with specific goals.

It is possible that this may change in the future; so please consider starring this project to keep an eye on future updates for opportunities to contribute and collaborate. Your support and understanding are highly valued.

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

Demonstrating empathy and kindness toward other people
Being respectful of differing opinions, viewpoints, and experiences
Giving and gracefully accepting constructive feedback
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

The use of sexualized language or imagery, and sexual attention or advances of any kind
Trolling, insulting or derogatory comments, and personal or political attacks
Public or private harassment
Publishing others' private information, such as a physical or email address, without their explicit permission
Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement by emailing the project owner at bitwizeshift@rodusek.com. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Project Governance

This project is a hobby-project I started for myself (@bitwizeshift), used as a learning opportunity for designing a videogame engine in Rust.

Decision Process

Whether or not an idea or feature-request will be implemented will largely come down to two criteria:

Is the feature something feasible to do in the spare time I have on weekends or after work?
Is the feature something fun to work on, and gratifying enough to receive positive returns after the fact?

Since this is something that must retain my interest in my spare time, it's important that this is reasonable to do and "fun" to achieve the result of.

Note: It is likely that, in the future, this project will grow to have a proper contribution policy so that others may provide back to this project. However, while this is still a hobby project for fun, the goal is for this to be a learning experience for myself.

Private Policy

Alloy does not log, collect, process, or share any personal or user data in any way.

In short: we don't track you, and we don't profile you. *Period.

However, it is important to note that Github, which hosts this project, does collect some aggregated metrics for the project -- such as clones, views, stars, etc. -- which are visible to contributors.

You can read more about this in Github's Privacy Policy.

Security Policy

Reporting a Security Vulnerability

This project has a small surface-area for general vulnerability exploitation, since it does not directly process any user data in any way, nor does it work with encrypted

As such, if you discover a security vulnerability within this project, please just open a Github Issue using the [Security Vulnerability] template. I appreciate your responsible disclosure and will make every effort to quickly address the issue.

When doing so, please provide the following details in your email:

Your affiliation (if applicable).
A detailed description of the vulnerability, including information on how to reproduce it.
Any potential impact of the vulnerability.

Once we receive your report, we will acknowledge the receipt of the vulnerability within 1 week, and strive to provide regular updates on our progress.

[Security Vulnerability]:

Security Practices

Dependency Vulnerability Scanning

We conduct weekly vulnerability scanning via cargo audit to identify and address potential security issues from a CVE database. This proactive approach helps us stay ahead of potential threats brought in from outdated and compromised dependencies.

Static CodeQL Analysis

We use rust clippy to ensure the overall quality code integrity within the codebase. This helps identify and address issues related to code structure, maintainability, and security best practices.

This is connected to CodeQL analysis, which detects and address security vulnerabilities in the codebase. CodeQL provides a powerful static analysis tool that aids in finding security-related issues early in the development process.

License Scanning

We use cargo deny to ensure that all 3rd-party dependencies use an OSI-approved license that is compatible with this project, and cargo about to generate a license manifest that ensures proper attribution is provided for the authors of any direct or indirect 3rd-party projects.

Note: If you believe there may be an issue with attribution in Alloy, please open a Github Issue and tell us what is missing! We make no effort to misrepresent the origin of software, and are thankful for all projects which we rely on -- and want to be responsible about attributing everyone accordingly.

Updates and Notifications

Security updates and notifications will be provided through the project's GitHub repository. Users are encouraged to watch the repository for any announcements regarding security releases or patches.

Supported Versions

We prioritize addressing security vulnerabilities in the latest stable release of the project. Users are strongly encouraged to keep their installations up-to-date with the latest releases.

License

By participating in this responsible disclosure process, you agree that your actions comply with applicable laws and regulations. We appreciate your contribution to the security of this project.

Thank you for helping to keep this project secure!

Support Policy

Overview

Thank you for using Alloy! We appreciate your interest and engagement with our project. This document outlines the support policy for this project. Please take a moment to read through this guide before seeking support.

How to Get Help

If you encounter any issues, have questions, or need assistance, please follow these steps:

Check Documentation: Refer to the project's documentation, README, and any provided guides to see if your question or issue is addressed.
Search Issues: Browse the project's GitHub issues to check if someone has already reported a similar problem or if a solution has been provided.
Ask the Community: If you can't find a solution in the documentation or existing issues, you can ask the community for help on the project's discussion forum.
Create an Issue: If your issue is not resolved through the above steps, or you've identified a bug, please open a new GitHub issue. Provide a clear and detailed description of the problem, including steps to reproduce it.

Bug Reports

When submitting bug reports, please include the following information:

Version of the project you are using.
A clear description of the issue.
Steps to reproduce the problem.
Any error messages or logs related to the issue.

Feature Requests

For feature requests, please provide a detailed explanation of the proposed feature and why you believe it would be valuable. This helps the maintainers understand your needs and consider the request.

Support Scope

Community Support: The project maintainers and the community will provide best-effort support, but there is no guarantee of response time or resolution.
Security Concerns: If you discover a security vulnerability, please report it through a normal Github issue. This project does not work with confidental data, and is not a high-risk system; so the surface-area for security issues is low.

Alloy Game Engine (Rust)