Architecture

Code Organization

Most of Punchy is organized into modules. Many of these modules represent a Bevy plugin, named after the module.

main.rs is responsible for initializing the engine config, installing the Bevy plugins, and spawning the initial game asset. All the rest of the game logic is in plugins.

Assets & Metadata

The goal is to have all of the game's content loaded dynamically based on a central index, the .game.yaml asset. This means that we should never include a specific asset by name in code.

The asset dir and the specific .game.yaml asset to be loaded is specified at runtime, with the defaults being assets/ and default.game.yaml.

The .game.yaml asset will itself reference other assets, such as level assets, which will in turn reference fighter assets. All of these interrelated assets make up the game content.

Important Modules

The three major modules involved in asset loading are:

• assets.rs
  • Contains the bevy asset loaders for all of our custom asset types.
• metadata.rs
  • Contains the struct definitions that make up most assets, and therefore determines the YAML structure most of the non-binary asset types.
  • Contains important structs, representing the YAML asset data such as GameMeta, LevelMeta, and FighterMeta.
  • Many of these structs contain fields like image and a corresponding field with a _handle suffix. These _handle fields are populated by the asset loader in assets.rs after deserialization.
• loading.rs
  • Contains the startup game and level loading code and hot reloading systems.

Scripts

In addition to YAML and artwork assets such as images and sounds, some of the game logic is implemented by script assets. The plan is to start trying to move as much of the gameplay code as we can into scripts, as we work on adding the capabilities that we need to the scripting API.

At the time of writing, scripting was recently added with #255, and the health item is the only item defined by a script so far.

A more in-depth overview of scripting can be found in Scripting.

Bevy Plugins

Some of the plugins include:

Movement Plugin ( movement.rs )

This plugin contains core primitives used to move things in the game, such as LinearVelocity, AngularVelocity, and Force. These behave similar to how they would in a physics simulation, but they don't represent a real physics simulation, just a simple constraint system.

Anything that needs to limit the movement of one or more entities may be implemented as a constraint system that gets run in a chain before the velocity_system. This is how player movement is constrained.

Damage Plugin ( damage.rs )

The damage plugin contains core components and events related to damage such as Health, Damageable, and DamageEvent.

Fighter State Plugin ( fighter_state.rs )

Manages the fighter state machine. See Fighter State Machine for a detailed explanation.

Lifetime Plugin ( lifetime.rs )

The lifetime plugin allows us to despawn entities after a timer by adding the LifetimeComponent.

Camera Plugin ( camera.rs )

Handles camera following and y sorting.

Audio Plugin ( audio.rs )

Installs audio player and sound playing systems.

UI Plugin ( ui.rs )

Responsible for game menus and in-game HUD and widgets.

Animation Plugin ( animation.rs )

Contains the sprite animation player and components.

Attack Plugin ( attack.rs )

Handles triggering and un-triggering attack collision boxes based on the AttackFrames component.

Localization Plugin ( localization.rs )

Contains the localization loader that is used for getting game translations, and an extension trait for helping read the translated values.

Platform Plugin ( platform.rs )

This contains platform specific integration code, such as the Storage interface which we use for saving game settings, and the system to set the web canvas size.

Loading Plugin ( loading.rs )

Initiates the load of game assets and levels. Also contains the systems that hot-reload specific asset types such as fighers.

Scripting Plugin ( scripting.rs )

The scripting plugin uses bevy_mod_js_scripting to enable the scripting API. It also implements custom JS bindings needed by punchy, such as the item grab and drop event readers.

Other Modules

Enemy AI ( enemy_ai.rs )

Contains the enemy AI logic. This is currently very simple. More details are in Enemy AI.

Engine Config ( config.rs )

This contains the engine config, which for native platforms is loaded from the CLI arguments, and for the web platform is loaded from the web query string.

Engine config is reserved for things that are required be configured before the game starts, such as the asset dir and log level.

enemy.rs, fighter.rs, item.rs

These contain bundles for fighters, enemies, and items. They my grow to contain systems related to those bundles later.

---

Discussion: #216