elnudev/hebi

A highly customizable snake clone made in Rust with the Bevy engine, named after the Japanese word for snake, 蛇.

Hebi 🐍

A highly customizable snake clone made in Rust with the Bevy engine, named after the Japanese word for snake, 蛇(へび).

Configuration

One of the things that sets apart Hebi from other snake clones is its rich configuration options. You can configure pretty much everything: the map, tick speed, food spawn rate, window scale, etc. You can even make your own custom color themes in addition to those provided! Keep in mind that Hebi is still very much a work-in-progress, so the names, behavior, and functionality of configuration options may change in the future.

To start configuring your game, create a config.toml file next to the Hebi executable.

Example config.toml

theme = "solarized_light"
seed = 42
food_ticks = 8

[map]
type = "corridors"
corridor_width = 2

Available configuration options

Name	Type	Default value	Function
theme	String	"dracula"	Sets what in-game color theme Hebi should use. For example, theme = "cavern" would load the theme file themes/cavern.toml. See Themes for more information on creating custom themes.
seed	u64	Random	Sets what seed should be used for deciding snake spawn locations, food spawn locations, and food colors. Since this is an unsigned number, it must be positive and less than or equal to 18446744073709551615.
map	Map	N/A	Sets the map data. See Maps for more info.
grid_scale	u32	36	Sets the number of pixels per grid square.
tick_length	f64	0.2	Sets the amount of time between in-game ticks in seconds. For a more challenging gameplay experience, try setting this to 0.15 or 0.1. For an easier gameplay experience for those with a slow reaction time, try setting this to 0.25 or 0.3.
food_ticks	u32	16	Sets the number of ticks between each food being spawned.
snake_spawn_segments	u32	2	Sets the number of segments the snake spawns with, including the head. 💥 Modifying this option from its default value may cause the game to crash.
snake_segment_despawn_interval	f64	0.1	Sets the interval between each segment despawning upon snake death in seconds. You can set this to 0 if you want the entire snake to despawn at once.
snake_respawn_delay	f64	0.5	Sets the delay in seconds between all segments despawning upon snake death and respawning.
eat_audio	String	"eat.wav"	Sets the audio file for the destruction of the snake's head and segments. The source for the default audio file is jsfxr. For example, eat_audio = "munch.wav" (fictional file) would load the audio file assets/sounds/munch.wav. Both .mp3 and .wav files are supported.
destroy_audio	String	"destroy.wav"	Sets the audio file for the destruction of the snake's head and segments. The source for the default audio file is jsfxr.
spawn_food_audio	String	"spawn_food.wav"	Sets the audio file for when food is spawned. The source for the default audio file is jsfxr.
spawn_snake_audio	String	"spawn_snake.wav"	Sets the audio file for when the snake is spawned. The source for the default audio file is jsfxr.

Themes

Along with the provided themes dracula, solarized_dark, solarized_light, and cavern, you can create your own themes! To get started, create a new file my_theme.toml in the themes folder, and open it in a text editor. To start off with, you can copy in the theme settings for cavern:

walls = "222233"
background = "000011"
snake = "ddddee"
food = ["5599ff", "ffc455", "ff6f55"]

To change a color, replace any of the hex codes provided, and make sure to remove the leading #. For food, you can put in as many colors as you like. If you decide to only have one food color, make sure to wrap it on square brackets: food = ["5599ff"].

To actually use your theme, see Configuration and add theme to your configuration file. If the theme can't file can't be found, the game will run, but as the colors are missing everything will be magenta. Likewise, if a color is missing or incorrectly formatted in your theme file, it will also show as magenta in-game.

Maps

Hebi currently ships with three different map generation modes: default, corridors, and custom.

Default

The default map type is the simplest, and it is what runs by default without any changes to the configuration file. To begin modifying, add the following to your config.toml file:

[map]
type = "default"

To override the default generation values, see the following table.

Configuration options

Name	Type	Default value	Function
width	u32	17	Sets game grid width, including walls.
height	u32	13	Sets game grid height, including walls.
corner_walls	u32	2	Sets the width and height of the corner walls. If you don't want any corner walls and an empty map, just set this to 0.
corner_walls_offset	i32	2	Sets the offset on the x- and y-axes of each of the corner walls from their respective corners of the map.

Corridors

The corridors map type is the only (relatively) complex generation type in the game currently. It sets up a bunch of vertical (or horizontal) corridors in the map of varying heights to increase game difficulty. To begin modifying add the following to your config.toml file:

[map]
type = "corridors"

To override the default generation values, see the following table.

Configuration options

Name	Type	Default value	Function
width	u32	34	Sets game grid width, including walls.
height	u32	17	Sets game grid height, including walls.
horizontal	bool	false	Sets whether to generate the map horizontally instead of vertically.
corridor_width	u32	3	Sets the width (height if horizontal = true) of each corridor. Corridors at the end of the map may be wider. This shouldn't be set to less than 2, since 1-wide corridors are dead ends and cannot be exited by the snake.
corridor_height	u32	10	Sets the maximum height (width if horizontal = true) of each corridor. For more control, see wall_variance.
top_corridor_offset	i32	3	Sets the horizontal (vertical if horizontal = true) offset of the top row of corridors.
bottom_corridor_offset	i32	0	Sets the horizontal (vertical if horizontal = true) offset of the bottom row of corridors.
wall_variance	f32	0.5	Sets the variance in the height (width if horizontal = true) of each wall. For example, with the default values where corridor_height = 10 and wall_variance = 0.5, that means that the actual heights of the walls in-game can vary anywhere in the top 50% of the maximum height, e.g. anywhere from 5 to 10.

Custom

If you aren't satisfied with the provided map generators, you can make your own maps! To get started, add the following to your config.toml file:

[map]
type = "custom"
data = """
#################
#               #
#  >      >  <  #
#  #      #  #  #
#  #      #  #  #
#               #
#  > <   >      #
#  # #   #      #
#  # #   # ##v  #
#               #
#################
"""

In the data field is where you make your map. A space means empty space and a pound sign # means a wall. Additionally, you must place at least one snake spawn point. A power symbol (^) is an up-facing spawn, a lower-case V (v) is down-facing spawn, a less-than sign (<) is a left-facing spawn, and a greater-than sign (>) is a right-facing spawn.

Contributing

If you feel like there's something you'd like to add to the game, feel free to make a fork and submit a pull request! I'll try to review it as soon as possible. If there's an issue with how I've structured the code in the project and you feel like there's a better way, however, please make an issue instead. Hebi is a learning project for me to learn Rust and Bevy, and I'd like to implement most of the core changes myself.

If you want to create a custom map generation type, a good starting point would be looking at src/maps/default.rs. Once you've got your generator working, submit it with a pull request! The more variety in game maps the better.

Building from source

Do you like what you see? Or maybe, you'd like to contribute to the project?

If you answered "Yes", then follow through these steps to get the game up and running, built right from source.

If you don't have Rust installed already, see the installation guide on Rust's official website and then come back once you're done.

Before we get to work, please note that Hebi uses some nightly Rust features (strip, which is one of the features used to create smaller binary sizes), that haven't been introduced to the stable channel. If you want to build Hebi without nightly Rust, remove or comment out the lines cargo-features = ["strip"] from the top and strip = true under [profile.release] in Cargo.toml.

1. Don't mind installing the channel? Then, let's default to it. If it's not already installed, then rustup will take care of that for you:

rustup default nightly

2. Now, clone the repository:

git clone https://github.com/ElnuDev/hebi.git

3. Great, let's jump inside the directory:

cd hebi

4. Okay, let's proceed by building the game; you know, turning that code into an executable.

• If you plan on contributing towards Hebi, we recommend building without the --release flag to cut down on compilation time:

cargo build

• If you're ready to take your Snake game to the next level and want the best experience, then --release is your friend:

cargo build --release

5. Now that you've built it yourself, you might want to configure Hebi.

Compressing with upx

The Linux and Windows (gross) builds provided in the releases section are compressed with UPX, the Ultimate Packer for eXecutables. UPX can reduce the binary size of Hebi by around 75%. If you want to make a distributable build of Hebi and have already used the --release flag for cargo build, you may also want to consider UPX. The cons of using UPX is that Hebi may be more likely to be flagged as malware by antivirus software, and there could be a performance penalty (unconfirmed, though it doesn't really matter much for such a simple game).

1. Install UPX

If you're on a Debian-based Linux distribution, you can install it with apt:

sudo apt install upx

If you're on Windows, you can download it from the UPX GitHub repository's releases section. To my knowledge, it's not available for winget, Window's new package manager, just yet.

2. Compress the binary

Ensure you're in the cloned Hebi folder first.

Linux:

upx --best --lzma target/release/hebi

Windows:

path\to\upx.exe --best --lzma target\release\hebi.exe

Distribution

For distribution, make sure to include the executable (hebi on Linux, hebi.exe on Windows) next to the themes and assets folder.

hebi's Issues

Split code into seperate files

700 line main.rs ?_? wtf

Add horizontal corridor mode to `corridors`' generation

Only systems should use `Res`, `ResMut`, and other `SystemParam`

Well, "should" is a strong word, but it is unneeded.

1. &Res<T> is pointless in systems, just use Res<T> (same goes for ResMut);
2. Outside systems, you shouldn't be dealing with the Res* types, just use &T or &mut T. Automatic deref takes care of the rest;
3. Haven't looked too deep, but the same goes for any other SystemParam (thing that can be a parameter to a system) wrapper-types.

Obvious exceptions are things like World, which are not wrappers but are a thing by themselves.

Let map types be serialized directly

Currently, the MapType trait cannot be serialized directly, since serde doesn't support serialization of traits (i.e. Box<dyn MapType>). As a work around, I'm using the Map enum with a variant for each individual map type. This works, but it's extremely verbose and requires a lot of duplicated code for each new map type.

Apparently, the typetag crate will fix this problem—it adds the ability to serialize and deserialize trait objects to serde.

Add map configuration documentation

Allow audio variations

Nice project.

If you are still looking for ideas you could implement you could allow the user to provide different audio variations for the same event. For example by allowing trailing numbers like so: eat_0.wav, eat_1.wav, eat_2.wav, etc.
Quite a lot of games do that, so the sounds don't get to repetitive.

Migrate to Bevy 0.6

Migration guide

Add ability to create custom input schemes

With the merging of #15 and c52b37a, Hebi supports four input schemes: the original arrow keys, WASD, HJKL, and the number pad. It would be nice if the user could create custom input schemes in the configuration file.

Pressing multiple direction keys ignores valid inputs

For example, if I'm moving right, then hold the left arrow key, then press up, nothing happens. Since the current input code has a strict priority in the form of the if chain, if I hold a key, any key of a lower priority is ignored.

Consider using key events instead of polling, so that the direction is always in sync with what the player last pressed.

Use .wav audio directly instead of converting to .mp3

Currently, the .wav files in the dev_assets folder cause errors when used, even with the wav feature of Bevy enabled. See this thread on the Bevy Discord server for more info. The files seem to play fine, so I'm not sure if this is some issue with the encoding of the files that jsfxr outputs, or if there's a potential bug in Bevy. Either way, it'd be way cleaner use the original .wav files directly instead of having to convert them .mp3 using a shell script like is being done currently and store both in this repository.

Prevent traversability issues for `corridors` map type

Currently, the corridors map type only inserts passageways in columns when they fill up the entire grid height. However, this is not the only scenario that will divide the map into multiple isolated rooms. More commonly, with an offset top or bottom corridor, two walls just a single x-coordinate appart that sum (but aren't individually) to more than the window height will touch, blocking the path. The following config.toml file will cause this issue:

[map]
type = "corridors"
width = 51
height = 19
corridor_width = 3
corridor_height = 14
top_corridor_offset = 1
bottom_corridor_offset = 0
wall_variance = 0.6

This shouldn't be too hard to fix, but it might be a bit fiddly. It isn't high priority.

Spawn functions clunkiness

You might have that feeling too:

Currently, if any piece of code wants to spawn a snake, segment, or wall, the system needs to query for those resources and pass them along up to and including the call site. There are like 8 parameters each so it is very verbose, and if you ever need to add something else to the spawn logic (e.g. suppose you later want to add sprites), updating the call sites will be a chore.

This can be substantially improved by either:

• Implementing your own Command, fetching the dependencies from the world inside the write function. This would make the call site look sorta like this:

  commands.add(SnakeSpawnCommand);

  Or even in this specific case, move the spawn-location-picking logic to the actual respawn system, and have the command take parameters:

  commands.add(SnakeSpawnCommand { x: 4, y: 6, direction: Direction::Up });

• Using an Event, and a late-running system that listens to it to do the actual spawning. Register an Event type, and make a system that runs as late as possible in the frame that reads the events and the required dependencies, spawning the entities. The call site would then look like:

  snake_spawn_event_writer.send(SnakeSpawnEvent { x: 4, y: 6, direction: Direction::Up });

Move map generators to separate executables

Moving each map generator (box, corridors, etc.) into a separate executable and then calling them from the main application instead of having them hard-coded in would increase customization potential for players, who could then create their own map generators for the game.

Add default values for map types

From the user's perspective, the way currently map values are passed in behaves differently than the rest of the config file: you have to put in every single map setting. There should be fallback values for each Map variant in a similar way to #[serde(default)] on Config.

Add build instructions

Decouple maps from config file

Kind of like how themes work currently. Name in config, load from a separate file.

Bonus points, would be cool if it used something like curl to be able to load remote files too, which would facilitate sharing.

In that case, it maybe would also make sense to be able to specify a seed for the random map generators? So people can share a specific map, not just the parameters.

Add gamepad support

Building with release flag hangs on MacOS 10.15.6

These are the steps I followed:

• Clone the repo
• Install rust nightly
• rustup show returns this:

~/hebi main
▲ rustup show
Default host: x86_64-apple-darwin
rustup home:  /Users/cog/.rustup

installed toolchains
--------------------

stable-x86_64-apple-darwin (default)
nightly-x86_64-apple-darwin

active toolchain
----------------

nightly-x86_64-apple-darwin (directory override for '/Users/cog/hebi')
rustc 1.57.0-nightly (c3c0f80d6 2021-09-14)

• run cargo build --release --verbose
• Cook an egg with my laptop fans
• Watch as hebi hangs on 299/300. I tried waiting up to 7 minutes and it didn't get unstuck. This is the output, if anyone can understand it:
  

Other notes: The build size is about 500MB. A lot better than 1.26GB, but far bigger than linux or windows builds.

Remove materials

Materials no longer seem necessary for sprites in Bevy 0.6, see the SpriteBundle and Sprite section in the migration guide. This should be done after migrating #25. For now, all material variables have been underscored to prevent unused variable warnings in b1184c7.