README.md 7.37 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Ever wanted to feel like an angel?  Are you sad that you can't do your annual
shift of wristband controls this year?  Fear not, we have exactly what you need!

Introducing:

![Engel Simulator 2020](misc/header.png)

**Engel Simulator 2020** is an upcoming rogue-like title where you collect
angel-hours to finally get that t-shirt you've always wanted (_t-shirt not
actually included_)!  Dive into a **realistic** and **immersive** (_2D
vector-art_) congress world and feel just like you did back when leaving the
house wasn't a crime.  We've got a wide range of angel-shifts (_TODO .._) that
**feel just like the real deal**.  But be careful to not loose your sanity,
because you'll be facing _dangerous_ obstacles:  From _eardrum-rupturing music_
to _tinfoil-hat-wearing conspiracy theorists_, we have got it all!

Rahix's avatar
Rahix committed
17
18
19
Do you have what it takes to get an angel shirt?  Play now at

[![https://engel-simulator.club](misc/website.png)](https://engel-simulator.club)
Rahix's avatar
Rahix committed
20
21
22
23
24
25
26
27
28

#### Disclaimer
... Yeah, we started working on this way too late and there's still lots of
features to work on.  If you want to help, please get in touch!  We're reachable
via

- **IRC**: `#rust` on `darkfasel.net`
- **Matrix**: `#rust:darkfasel.net`
- Open an issue here in this GitLab project
Rahix's avatar
Rahix committed
29
30

# Hacking
Rahix's avatar
Rahix committed
31
- [Project Structure](#project-structure)
Rahix's avatar
Rahix committed
32
33
- [Build Dependencies](#build-dependencies)
- [Development Environment](#development-environment)
Rahix's avatar
Rahix committed
34
- [Level Design](#level-design)
Rahix's avatar
Rahix committed
35
36
37
38

## Project Structure
The project is mainly split into two parts:  The game logic, written in Rust,
living in `src/`, and the web-frontend in `www/src/` which is mainly HTML and
Rahix's avatar
Rahix committed
39
40
41
SCSS + a bit of JS glue code.  Resources like sprites and levels live in
`www/resources/`.  Additionally, some custom helper JavaScript (TypeScript
actually) functions which are called from Rust are defined in `rust-web-modules/`.
Rahix's avatar
Rahix committed
42
43

#### `src/` - Rust Game Logic
Rahix's avatar
Rahix committed
44
45
46
47
We're using the [`legion`](https://github.com/amethyst/legion) ECS framework for
the in-game world and a custom state-machine for managing the overall gamestate.

- `src/utils.rs`: Javascript-Gluecode, e.g. a `document.getElementById()`
Rahix's avatar
Rahix committed
48
49
  wrapper.
- `src/colliders.rs`: `ncollide2d` integration
Rahix's avatar
Rahix committed
50
51
52
53
54
55
56
57
58
59
- `src/components/`: Components for game entities
- `src/resources/`: Game-global resources like a global clock or the canvas
  rendering proxy.
- `src/systems/`: ECS systems for the game.
- `src/entities/`: Entity factories for instanciation different kinds of
  entities.
- `src/gamestate.rs`: Game state machine implementation.
- `src/states/`: Game-states like _Heaven_, _In-Game_, _Main-Menu_, etc.  The
  most important one is probably `src/states/ingame.rs` which is where all the
  ECS magic happens.
Rahix's avatar
Rahix committed
60
- `src/angel_shifts/`: Implementations of the different angel shifts.
Rahix's avatar
Rahix committed
61
62
63
64
65

#### `rust-web-modules/` - TypeScript helpers for Rust
Some things are just super ugly to do in Rust directly (anything related to the
DOM) so we have a few helper functions written in TypeScript to "offload" this
work.
Rahix's avatar
Rahix committed
66
67
68
69
70
71

#### `www/src/` - Web Frontend
- `www/src/index.html`: Main HTML Document
- `www/src/styles.scss`: Stylesheet using Sass
- `www/src/_rc3-*`: Styles and Fonts for RC3

Rahix's avatar
Rahix committed
72
#### `www/resources/` - Sprites and Levels
Rahix's avatar
Rahix committed
73
74
75
76
- `www/resources/levels/` - Maps, see [Level Design](#level-design) for all the
  gory details.
- `www/resources/sprites/` - Sprites for in-game entities.  Sprites are loaded
  via entries in `src/sprites.rs`.
Rahix's avatar
Rahix committed
77

Rahix's avatar
Rahix committed
78
## Build Dependencies
Rahix's avatar
Rahix committed
79
- `rustc` & `cargo` **latest stable** (=1.48.0 as of now).  Best install them via [`rustup`] ...
Rahix's avatar
Rahix committed
80
81
82
83
84
85
86
87
- [`wasm-pack`]
- `npm`
- (optional: [`cargo-watch`])

[`wasm-pack`]: https://github.com/rustwasm/wasm-pack
[`rustup`]: https://rustup.rs/
[`cargo-watch`]: https://github.com/passcod/cargo-watch

Rahix's avatar
Rahix committed
88
89
90
91
92
93
With those dependencies installed, run

```bash
cd www/ && npm install
```

Rahix's avatar
Rahix committed
94
95
96
97
98
99
## Development Environment
Open two shell sessions, one for the rust build and one for the webpack dev
server:

```bash
# For Rust:
Rahix's avatar
Rahix committed
100
cargo watch -s "wasm-pack build --dev" --watch src
Rahix's avatar
Rahix committed
101
# or, if you don't use cargo-watch, just run
Rahix's avatar
Rahix committed
102
wasm-pack build --dev
Rahix's avatar
Rahix committed
103
104
105

# For the webpack dev server:
cd www/
106
npm run rust-web-modules
Rahix's avatar
Rahix committed
107
npm run start
Rahix's avatar
Rahix committed
108
109
110
111
```

Then point your browser to `http://localhost:8080` and start hacking!  The
website will automatically reload when any changes are done to the web sources
Rahix's avatar
Rahix committed
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
(`www/`) or the Rust sources (`src/`).  If you change the `rust-web-modules/`
you'll have to manually run `npm run rust-web-modules` again (please fix!).

## Level Design
We're using an _Inkscape SVG_ file as the level format (yes, the inkscape
specific tags are important) and thus we use [Inkscape](https://inkscape.org/)
as the level editor.  **There are a lot of pitfalls in designing levels so**
**please read this guide carefully!**

### Colors
We have created an Inkscape palette with the RC3 colors for your convenience.
You can find it in [`misc/rc3-palette.gpl`](misc/rc3-palette.gpl).  To use it,
copy this file to `~/.config/inkscape/palettes/rc3-palette.gpl`.  Then, select
it in Inkscape in the bottom right corner like this:

![select palette in Inkscape](misc/select-palette.png)

To use the colors, **click** the swatches to set _fill-color_ for the currently
selected objects or **shift-click** to set _stroke-color_.

Please use the last color of the palette (`#100e23`) as the level background.

### Layers
The level contains a number of layers which the game-engine expects to exist:

- `background`: Any graphic elements to be shown _below_ the player and game
  objects.
- `collider`: A special layer that is not shown in-game which defines static map
  colliders.  There are a lot of restrictions in this layer, please see [Map
  Colliders](#map-colliders-collider-layer) for details.
- `spawns`: Spawnpoints for game objects.  This layer is also not shown and has
  special semantics.  See [Spawnpoints](#spawnpoints-spawns-layer).
- `foreground`: Any graphic elements to be drawn _on top of_ the player and
  game-objects.

### Map Colliders: `collider` Layer
The `collider` layer defines static colliders for the map.  Only the following
SVG elements may appear in this layer:

- `<rect />`: A rectangle collider (**Must not be rotated, this is not yet**
  **supported!**).  Created in Inkscape using the _Rectangle_ tool (shortcut: `R`).
- `<circle />`: A circular collider.  Created in Inkscape using the _Ellipse_
  tool (shortcut: `E`).  **Careful**: Keep `CTRL` pressed while creating the
  circle, otherwise you'll get an `<ellipse />` which is not supported.

For consistency, please color all colliders in 50% transparent red (`#ff000080`)
with no stroke.

### Spawnpoints: `spawns` Layer
The `spawns` layer defines all possible spawn points for game entities.  This
layer should only contain SVG `<text />` elements.  The origin point for the
text object describes the spawnpoint, the "text" describes _what_ can be
spawned.  The following spawnpoints are currently known:

- `player`: Defines a possible player spawn location.  One will be randomly
  selected when entering the level.
- `bottledrop`: Defines a possible location for a bottle drop point.  Currently,
  4 will be randomly selected during level load.

Please use the `monospace` font and white text color for consistency.
Rahix's avatar
Rahix committed
172
173
174
175
176
177
178
179
180
181
182

---

# License
Licensed under the GNU General Public License v3.0 ([COPYING](COPYING) or
<https://www.gnu.org/licenses/gpl-3.0-standalone.html>).

## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, shall be licensed as above, without any
additional terms or conditions.