README.md 6.98 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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!

Do you have what it takes to get an angel shirt?

#### 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
27
28

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

## 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
37
38
39
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
40
41

#### `src/` - Rust Game Logic
Rahix's avatar
Rahix committed
42
43
44
45
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
46
47
  wrapper.
- `src/colliders.rs`: `ncollide2d` integration
Rahix's avatar
Rahix committed
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
- `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.

#### `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
63
64
65
66
67
68

#### `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
69
70
#### `www/resources/` - Sprites and Levels
- TODO
Rahix's avatar
Rahix committed
71

Rahix's avatar
Rahix committed
72
## Build Dependencies
Rahix's avatar
Rahix committed
73
74
75
76
77
78
79
80
81
- `rustc` & `cargo` (duh ... best install them via [`rustup`])
- [`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
82
83
84
85
86
87
With those dependencies installed, run

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

Rahix's avatar
Rahix committed
88
89
90
91
92
93
## 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
94
cargo watch -s "wasm-pack build --dev" --watch src
Rahix's avatar
Rahix committed
95
# or, if you don't use cargo-watch, just run
Rahix's avatar
Rahix committed
96
wasm-pack build --dev
Rahix's avatar
Rahix committed
97
98
99

# For the webpack dev server:
cd www/
100
npm run rust-web-modules
Rahix's avatar
Rahix committed
101
npm run start
Rahix's avatar
Rahix committed
102
103
104
105
```

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
106
107
108
109
110
111
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
(`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
166
167
168
169
170
171
172
173
174
175
176

---

# 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.