{"id":28067387,"url":"https://github.com/IvoryDuke/HillVacuum","last_synced_at":"2025-05-12T16:01:51.185Z","repository":{"id":236539275,"uuid":"771720744","full_name":"IvoryDuke/HillVacuum","owner":"IvoryDuke","description":"A bevy-based 2D map editor.","archived":false,"fork":false,"pushed_at":"2025-05-09T22:14:12.000Z","size":3848,"stargazers_count":49,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-09T23:19:25.027Z","etag":null,"topics":["bevy","game-development","map-editor","open-source","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IvoryDuke.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-13T20:28:56.000Z","updated_at":"2025-05-09T22:14:15.000Z","dependencies_parsed_at":"2024-05-17T17:24:39.889Z","dependency_job_id":"95041736-5662-49e0-9c6c-7dcf475649d0","html_url":"https://github.com/IvoryDuke/HillVacuum","commit_stats":null,"previous_names":["ivoryduke/hillvacuum"],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvoryDuke%2FHillVacuum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvoryDuke%2FHillVacuum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvoryDuke%2FHillVacuum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvoryDuke%2FHillVacuum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IvoryDuke","download_url":"https://codeload.github.com/IvoryDuke/HillVacuum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253773089,"owners_count":21962187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bevy","game-development","map-editor","open-source","rust"],"created_at":"2025-05-12T16:01:23.166Z","updated_at":"2025-05-12T16:01:51.140Z","avatar_url":"https://github.com/IvoryDuke.png","language":"Rust","funding_links":[],"categories":["Editors and Workflow"],"sub_categories":[],"readme":"[![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](https://github.com/IvoryDuke/HillVacuum#license)\n\n## What is HillVacuum?\n`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.\n\n## How is HillVacuum?\nFor those who do not mind reading, HV features a manual, which can be referenced in three ways:  \n- the `MANUAL.md` file;  \n- the `MANUAL.pdf` file;  \n- the `Manual` window built in the editor which can be opened through the keyboard combination `` Ctrl+` ``.  \n\nFor the rest, there's this [video](https://youtu.be/c5lakP_V1n0).\n\n![hv_1](previews/hv_1.png)\n![hv_2](previews/hv_2.png)\n\n## Keywords\n\n### Brush\nA 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.  \nBrushes can also be assigned a path that describes how it moves in the bidimensional space and that can be edited with the Path tool.  \nFinally, 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.\n\n### Thing\nA 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.  \nThings can also be assigned a path that describes how it moves in the bidimensional space and that can be edited with the Path tool.  \nThings 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.  \nIf defined in the .ini files, the things must follow a similar format:\n```ini\n[Name]\nwidth = N\nheight = M\nid = ID\npreview = TEX\n```\nWhere `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.  \nIf the texture assigned to the Thing has an animation, the texture will be drawn accordingly.  \n  \nIf a thing in the `HillVacuumPlugin` has the same `ID` as one loaded from file, the latter will overwrite the former.  \nFinally, 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.\n  \nThings can be reloaded while the application is running through the UI button in the Options menu.\n\n### Properties\nProperties are custom user defined values which can be associated to brushes and things.  \nSuch values can be added to the application through the `brush_properties` and `thing_properties` fields of the `HillVacuumPlugin`.  \nProperties can be edited per-entity using the properties window.  \nCurrently supported value types are `bool`, `u8`, `u16`, `u32`, `u64`, `u128`, `i8`, `i16`, `i32`, `i64`, `i128`, `f32`, `f64`, and `String`.  \n  \n!!! 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.\n\n### Texture\nTextures must be placed in the `assets/textures/` folder to be loaded.  \nThe texture editor can be opened at any time to edit the properties of the textures of the selected brushes.  \nEntity, 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`.  \nTextures 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.  \nWhen editing a list type animation, it is possible to add a texture by clicking it with the left mouse button.  \nTo 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.  \n  \nTextures can be reloaded while the application is running through the UI button in the Options menu.  \nDefault textures animation can be exported and imported between map files. The file extension of the animations files is `.anms`.\n\n### Prop\nA prop is a collection of entities which can be painted around the map like the brushes of an image editing tool.  \nEach prop has a pivot, the point relative to which it is painted onto the map.  \nProps can be imported and exported between map files. The file extension of the props files is `.prps`.\n\n### Path\nA path is a series of nodes describing how the entity that owns it moves over time around the map.  \nNodes have five customizable parameters:  \n- `Standby`: the amount of time the entity stands still before starting to move to the next node;  \n- `Min speed`: the minimum speed the entity moves;  \n- `Max speed`: the maximum speed the entity reaches;  \n- `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;  \n- `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.  \n\nThe 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.  \nA 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.\n\n### Grid\nThe 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.\n\n## Files\nHV creates three types of files, all of which are relatively simple:\n- `.hv` is the map file;\n```\n-------------------------------\n| Version number              |\n-------------------------------\n| Header                      |\n| brushes amount              |\n| things amount               |\n| animations amount           |\n| props amount                |\n-------------------------------\n| Grid settings (skew, angle) |\n-------------------------------\n| Animations                  |\n-------------------------------\n| Default brush properties    |\n-------------------------------\n| Default thing properties    |\n-------------------------------\n| Brushes                     |\n-------------------------------\n| Things                      |\n-------------------------------\n| Props                       |\n-------------------------------\n```\n- `.anms` is the \"animations only\" file, which can be used to exchange animations between maps;\n```\n-------------------------------\n| Version number              |\n-------------------------------\n| animations amount (usize)   |\n-------------------------------\n| Animations                  |\n-------------------------------\n```\n- `.prps` is the \"props only\" file, which can be used to exchange props between maps.\n```\n-------------------------------\n| Version number              |\n-------------------------------\n| props amount (usize)        |\n-------------------------------\n| Props                       |\n-------------------------------\n```\n\n## Getting started\nHV can be compiled as a standalone executable simply compiling the source code (Linux distributions may require the installation of extra libraries).\n```sh\ncargo run\n```\n\nOtherwise it can be integrated in your own project as such:\n```rust\nfn main()\n{\n    bevy::app::App::new()\n        .add_plugins(hill_vacuum::HillVacuumPlugin::default())\n        .run();\n}\n```\n\nMap 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.\nAssuming the path of the map file was passed as an argument to the exporting executable the code will look something like this:\n```rust\nfn main()\n{\n    let exporter = hill_vacuum::Exporter::new(\u0026std::env::args().collect::\u003cVec\u003c_\u003e\u003e()[0]);\n    // Your code.\n}\n```\nThe map being edited can be exported through such an executable through the File-\u003eExport command in the editor.\nThe executable can be picked through Options-\u003eExporter.\n\n## Features\n- `dynamic_linking`: enables the `bevy` feature of the same name;\n- `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.\n\n## !! WARNING\n- [The only thing I know for real](https://youtu.be/T928kJvqTlo?si=2_YnB2pEuFSKKq-j), there will be bugs.  \n  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;\n- 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: \u003chttps://docs.rs/rfd/latest/rfd/\u003e):\n\n| Distribution    | Installation Command     |\n| --------------- | ------------------------ |\n| Fedora          | dnf install gtk3-devel   |\n| Arch            | pacman -S gtk3           |\n| Debian \u0026 Ubuntu | apt install libgtk-3-dev |\n\n## Misc\nIn 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIvoryDuke%2FHillVacuum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIvoryDuke%2FHillVacuum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIvoryDuke%2FHillVacuum/lists"}