Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ivoryduke/hillvacuum

A bevy-based 2D map editor.
https://github.com/ivoryduke/hillvacuum

bevy game-development map-editor open-source rust

Last synced: 6 days ago
JSON representation

A bevy-based 2D map editor.

Host: GitHub
URL: https://github.com/ivoryduke/hillvacuum
Owner: IvoryDuke
License: apache-2.0
Created: 2024-03-13T20:28:56.000Z (9 months ago)
Default Branch: main
Last Pushed: 2024-10-29T13:27:10.000Z (about 2 months ago)
Last Synced: 2024-10-29T16:05:20.758Z (about 2 months ago)
Topics: bevy, game-development, map-editor, open-source, rust
Language: Rust
Homepage:
Size: 5.03 MB
Stars: 37
Watchers: 2
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE

Awesome Lists containing this project

README

[![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](https://github.com/IvoryDuke/HillVacuum#license)

## What is HillVacuum?
`HillVacuum` is a `Doom Builder` and `TrenchBroom` inspired editor that allows the creation of bidimensional maps through the manipulation of convex polygons, placement of items and entities, and texture mapping.

## Why is HillVacuum?
- I wanted to learn Rust;
- I wanted to create my editor;
- I got tired of manually typing the coordinates of the collision polygons in a text file.

## How is HillVacuum?
For those who do not mind reading, HV features a manual, which can be referenced in three ways:
- the `MANUAL.md` file;
- the `MANUAL.pdf` file;
- the `Manual` window built in the editor which can be opened through the keyboard combination `` Ctrl+` ``.

For the rest, there's this [video](https://youtu.be/c5lakP_V1n0).

![hv_1](previews/hv_1.png)
![hv_2](previews/hv_2.png)

## Keywords

### Brush
A brush is a convex polygonal surfaces. It can have an associated texture which can either be drawn filling its surface or as a sprite. The sprite can be displaced independently of the brush's surface.
Brushes can also be assigned a path that describes how it moves in the bidimensional space and that can be edited with the Path tool.
Finally, brushes have a built-in property, `collision`, which determines whether they should represent a clipping surface or not. It can be edited in the properties window.

### Thing
A thing is an object which can be placed around the map. It is characterized by an ID, a width and height, a name, and a texture which represents it.
Things can also be assigned a path that describes how it moves in the bidimensional space and that can be edited with the Path tool.
Things can either be defined in one or many .ini files to be placed in the `assets/things/` folder or, if `HillVacuum` is used as a library, adding them to the `hardcoded_things` field of the `HillVacuumPlugin` to insert them in the bevy App.
If defined in the .ini files, the things must follow a similar format:
```ini
[Name]
width = N
height = M
id = ID
preview = TEX
```
Where `ID` is an unique identifier between 0 and 65534, and `TEX` is the name of the texture (without the file extension) to be drawn along with the bounding box.
If the texture assigned to the Thing has an animation, the texture will be drawn accordingly.

If a thing in the `HillVacuumPlugin` has the same `ID` as one loaded from file, the latter will overwrite the former.
Finally, things have two built-in properties, `angle` and `draw height`. The orientation of the arrow drawn on top of the things will change based on the value of `angle`, and `draw height` determines its draw order. They can be edited in the properties window.

Things can be reloaded while the application is running through the UI button in the Options menu.

### Properties
Properties are custom user defined values which can be associated to brushes and things.
Such values can be added to the application through the `brush_properties` and `thing_properties` fields of the `HillVacuumPlugin`.
Properties can be edited per-entity using the properties window.
Currently supported value types are `bool`, `u8`, `u16`, `u32`, `u64`, `u128`, `i8`, `i16`, `i32`, `i64`, `i128`, `f32`, `f64`, and `String`.

!!! If a saved map contains properties that differ in type and/or name from the ones defined in the aforementioned resources, a warning window will appear on screen when trying to load the `.hv` file, asking whether you'd like to use the app or map ones.

### Texture
Textures must be placed in the `assets/textures/` folder to be loaded.
The texture editor can be opened at any time to edit the properties of the textures of the selected brushes.
Entity, scale, and rotate tool also feature texture editing capabilities. These capabilities can be either enabled through the dedicated "Target" UI element in the bottom left area, or by pressing `Alt + texture editor bind`.
Textures can have an associated animation which can either consist of a list of textures to display, each one for a specific time, or an atlas of textures generated by subdividing the textures in subareas. The animations can be applied to the texture as a default or to the texture of the selected brushes only.
When editing a list type animation, it is possible to add a texture by clicking it with the left mouse button.
To edit the animation of a texture that is not the one of the selected brushes, it needs to be pressed with the right mouse button.

Textures can be reloaded while the application is running through the UI button in the Options menu.
Default textures animation can be exported and imported between map files. The file extension of the animations files is `.anms`.

### Prop
A prop is a collection of entities which can be painted around the map like the brushes of an image editing tool.
Each prop has a pivot, the point relative to which it is painted onto the map.
Props can be imported and exported between map files. The file extension of the props files is `.prps`.

### Path
A path is a series of nodes describing how the entity that owns it moves over time around the map.
Nodes have five customizable parameters:
- `Standby`: the amount of time the entity stands still before starting to move to the next node;
- `Min speed`: the minimum speed the entity moves;
- `Max speed`: the maximum speed the entity reaches;
- `Accel (%)`: the percentage of the distance between the current node and the next that the entity will spend accelerating from the minimum to the maximum speed;
- `Decel (%)`: the percentage of the distance between the current node and the next that the entity will spend decelerating from the maximum to the minimum speed.

The maximum speed can never be lower than the minimum speed and it can never be 0. The acceleration and deceleration percentages always amount to 100% at most. The acceleration phase always comes before the deceleration one.
A path can have overlapping nodes. However, two consecutive nodes cannot overlap. Overlapping nodes are clearly shown in the tooltips. Therefore, it is highly encouraged to leave them on.

### Grid
The map grid can be skewed and/or rotated to give the map an isometric look. These two parameters can be edited in the settings window.

## Getting started
HV can be compiled as a standalone executable simply compiling the source code (Linux distributions may require the installation of extra libraries).
```sh
cargo run
```

Otherwise it can be integrated in your own project as such:
```rust
fn main()
{
bevy::app::App::new()
.add_plugins(hill_vacuum::HillVacuumPlugin::default())
.run();
}
```

Map files can be read through the `Exporter` struct that will return lists of all the brushes and things, which can then be exported as desired.
Assuming the path of the map file was passed as an argument to the exporting executable the code will look something like this:
```rust
fn main()
{
let exporter = hill_vacuum::Exporter::new(&std::env::args().collect::>()[0]);
// Your code.
}
```
The map being edited can be exported through such an executable through the File->Export command in the editor.
The executable can be picked through Options->Exporter.

## Features
- `dynamic_linking`: enables the `bevy` feature of the same name;
- `ui`: enables the `HillVacuumPlugin` and therefore the UI editor. Enabled by default, it is recommended to turn it off, for example, when creating an executable to export a map using the `Exporter` struct.

## !! WARNING
- [The only thing I know for real](https://youtu.be/T928kJvqTlo?si=2_YnB2pEuFSKKq-j), there will be bugs.
HV has been thoroughly tested but is still in its early releases, so there might be issues that lead to crashes due to unrecoverable errors. It is strongly recommended to save often;
- On Linux, HV requires the C library and development headers of GTK3 to be installed to build. If not installed, HV will crash any time a message dialog must be displayed. The package names on various distributions are (source: ):

| Distribution | Installation Command |
| --------------- | ------------------------ |
| Fedora | dnf install gtk3-devel |
| Arch | pacman -S gtk3 |
| Debian & Ubuntu | apt install libgtk-3-dev |

## Misc
In order to close the in-editor windows through the keyboard the `F4` key needs to be pressed (similar to pressing `Alt+F4` to close OS windows).

## FAQ
### It's "vertices", not "vertexes"
First of all .
Finally, [if popular culture has taught us anything is that 'c's are not extreme](https://youtu.be/mols06iqcfA?si=ijCNCojPOR4rC8n1&t=336).

### Actually if you read the "Rust programming language" book it clearly says: "It’s good style to place the opening curly bracket on the same line as the function declaration, adding one space in between."
There's a lot of talk around the internet about respecting each other's differences, and rightfully so. So I would appreciate it if people could respect this difference of mine.