Initial README.

README.md

@@ -0,0 +1,54 @@
+# Blackout
+
+_Blackout_ is an opinionated audio game framework for [Bevy](https://www.bevyengine.org). Because it is perpetually evolving, it is unversioned and only available via Git for now. If you're looking for a stable, documented audio game engine, this isn't it. But if you're looking for a battle-tested and perpetually improving set of utilities for building immersive, audio-only arcade/adventure games, this is for you.
+
+**Fair warning:** This code gets the job done, but much of it can certainly stand to be improved. If you ever want to be driven to insanity, try using physics/visibility systems as a blind person. You can't just draw a collider debug shape and eyeball it. Instead, you have to spit out bunches and bunches of numbers, carefully check each one, and figure out where it might break in future iterations of the game loop. I'm perpetually finding things that I can fix, and if you've got contributions then I welcome them. I've disabled issues on this repository for now because I don't really have the bandwidth to accept critiques without fixes for this project.
+
+## What's in the box?
+
+_Blackout_ uses a few other libraries for its magic:
+
+* [bevy_openal](https://github.com/lightsoutgames/bevy_openal): Audio
+* [bevy_input_actionmap](https://github.com/lightsoutgames/bevy_input_actionmap): Mapping inputs to actions
+* [mapgen](https://docs.rs/mapgen/latest/mapgen/): Map generation
+
+It provides, including but not limited to:
+
+* commands
+  * `RunIfExists` extension for only running a given command if its entity exists
+* core
+  * `Coordinates` component for managing 2-D positions
+  * `PointLike` trait for distance and other calculations between `Coordinates` and `Coordinates`-like things (I.e. `(f32, f32)`, `(i32, i32)`, ...)
+  * `Angle` type for handling angles in degrees/radians
+  * `Direction` type for working with cardinal/movement directions, converting to/from angles, etc.
+  * Configuration for syncing pixel-to-meter ratios between OpenAL and Rapier
+  * Systems that try keeping the mess of Bevy/Blackout/Rapier position types synced
+  * `Player` component for use in other modules/plugins
+* log
+  * Simple log component, automatically read via text-to-speech when appended to
+* map
+  * `Area` type for storing AABBs associated with map rooms
+  * Optionally logs descriptions of newly-entered areas, either by dimensions or by name
+  * Map generator filter for creating mazes of joined rooms
+  * Scans maps for portals (I.e. where rooms become doors, corridors, etc. Useful for adding door creeking sounds, wind for tunnel mouths, etc.)
+  * Creates physical colliders for map obstructions. Can either create one per blocked tile, or trace and combine blocked tiles into larger colliders
+* navigation
+  * Simple 8-way or rotational movement controllers
+  * `Speed` component for more easily scaling velocity
+* pathfinding
+  * Simple A* pathfinding
+* Exploration
+  * Adds a moveable cursor for exploring maps either by tile or by entity type
+  * If configured, supports navigating to the selected tile via pathfinding
+* visibility
+  * Shadowcast-based visibility system, integrated with maps, that generates events on visibility state change
+* sound
+  * Footsteps with configurable stride length that only play when moving
+  * Sound icons that play at configurable intervals when entities become visible
+* pitch_shift
+  * Automatically pitch-shifts sounds down by a configurable percentage when they're behind the player
+* utils
+  * Poorly-named `target_and_other` function for taking 2 entities, a predecate, and returning `Some((match, other))` if one matches or `None` if neither do. Good for, say, taking in a collision pair and returning a bullet entity first
+* error
+  * Logger for logging panic stacktraces
+  * Panic handler for sending stacktraces to [Sentry](https://sentry.io) in release builds