minerace/README.md

# Minerace

Minerace is a racing game for Minecraft. It is made as a datapack,
and is thus playable in vanilla Minecraft.

The datapack is currently made for 1.16.5, use in other versions is
at your own risk.

**Be warned, the datapack is still in early development and may
break and change in any way.**

There is an official server at `185.224.129.232`.

## How to play

To play the game, enter the queue and start the race. This may vary
depending on your world. If you don't have a world, see the
installation section below.
Up to eight players can play together in a race.

Item slot 1 makes your kart accelerate. The kart will rotate towards
the direction you are facing, but it's not immediate.
When you need to brake, select item slot 2.
You are recommended to start braking a few blocks before the road
turns, so that you have enough time to rotate your kart.


### Items

The game has items that are obtained from item boxes. Current items
are:
- gold: increases speed slightly on use.
- slime: a slime can be placed. Slimes stun things that hit them.
- turtle: bounces on walls and dies after a timeout, a certain amount
of bounces or a stun, whichever happens first.
- star: increases speed and grants invulnerability. The user's kart
will explode and stun anything it hits. Hit karts lose their items.
- missile: lets players shoot a missile in the direction the user is
facing.
- lightning: all karts ahead of the user will be stunned and lose
their items.


## Installation

If you don't already have a world (no world is provided yet),
create a new one, preferably empty, as the superflat preset
"The Void" does. Set game rules so that no mobs spawn and no damage
is dealt to players. The default gamemode should be adventure mode.

To use the datapack, clone this repository into the desired world's
`datapacks` folder. You are suggested to not use the vanilla datapack
as it has annoying advancements. The rest of the features from the
vanilla datapack are provided by this datapack, so it can be used
alone out of the box. Note that some expectations are made by the
datapack, such as a barrel or other container at position 1000 0 0
and in future versions a pillar blocks at 1000 0 where no two
adjacing blocks are the same. Chunk 62 0 is expected to be force
loaded.

A lobby is expected to be at 0 50 0, with a way to start the race
using `/function emk:race/launch` (for example with a sign). There
is a queue area as defined in `data/emk/functions/tick.mcfunction`,
which should be modified to your needs. You may remove the queue
area and replace it with your own management. Players are
automatically removed from the queue when launching. Up to 8 players
in the queue will be launched to a race, so make sure to get a way
to enter and leave the queue.

Map locations are defined in
`data/emk/functions/race/launch.mcfunction` and should be modified
to your world's needs. You will also need to edit
`data/emk/loot_tables/map.json` to adjust the maximum map ID.
More information about maps is found further in this file.

When ready, run `/function emk:setup` to (hopefully) complete the
install. This sets up scores and the queue bossbar used by the game.


## Building maps

You are recommended to read through this entire section before
building your map. When using your own world, this is usually a good
idea, this game is no fun without maps!


### The start

When starting a race, all karts are facing south and are expected to
pass the finish line once to start the first lap.

Below is a depiction of how the map's start is suggested to be like,
with the first line being the southmost position.  
`#` indicates the finish line where the start checkpoint should be.
`*` is the starting position for a kart, facing the finish line.  
`_` is a road block, which does not have the tag `emk:offroad`. Edit
`data/emk/tags/block/offroad.json` if the standard setup does not
suit you.  
`!` is the starting position, the coordinates of this position will
be used later.

```
#######
_______
_*_!___
___*___
_____*_
_*_____
___*___
_____*_
_*_____
___*___
_______
```


### Building guidelines

Roads are suggested to be at the very minimum 7 blocks wide.
9-11 blocks width may be challenging, wider makes the map really easy
to get through. One may choose to leave a padding of offroad blocks
before the player hits walls, but not doing this is fine too.

Karts can drive through two blocks tall spaces, although this makes
it hard to see, especially for players using taller karts, so a
suggested minimum is three blocks.

Remember that karts can climb terrain - the road does not need to be
flat. Handling of half blocks like slabs will be implemented in
future versions.

To make the map more interesting, item boxes can be spawned. To do
so, use `/function emk:box/summon`. Misplaced boxes can be removed
with `/kill @e[tag=emk-box,sort=nearest,limit=1]` *combined* with
`/kill @e[type=minecraft:end_crystal,sort=nearest,limit=1]`
(advanced users may adjust the commands to their needs).
**Do not punch the end crystals - they will explode!** (unless you
are in adventure mode.)

#### Checkpoints

Maps use checkpoints of wool blocks located at y level 0. Karts need
to pass all checkpoints to complete one lap. The order of the
checkpoints is the same as in the creative inventory, starting at
white (the finish line) and last one being black.
Checkpoints are easier to add when there's a finished track.

Building checkpoints should be pretty straightforward. Keep in mind
that there should always be a way to drive above checkpoints, so
walling the entire track is recommended - otherwise confusion may
arise.

Due to checkpoints, a map floor is suggested, but not having one is
fine too.


### Map testing

Karts can be summoned with `/function emk:kart/summon`. To destroy a
kart, either drive it off into the void or run
`/kill @e[tag=emk-kart,sort=nearest,limit=1]`. The remaining entity
may now be safely killed too. Spawning more than one kart per player
has unexpected effects.


### Finishing the map

Run the command `/function emk:race/summon` to summon a map entity.
All entities belonging to the race are expected to stay within 500
blocks of the map entity. Keep maps far enough away from each other
so that there is no overlap of the map entities' radii.
Preferably, run the command at the position marked with an `!`.

Set the map's name with the following command:
```
/data merge entity @e[tag=emk-map,distance=..500,limit=1] {CustomName:'{"text":"My new map"}'}
```

Set the map's amount of laps with
```
/scoreboard players set @e[tag=emk-map,distance=..500] emk-lap N
```
where you replace `N` with the desired amount of laps.

### Adding maps to the pool

When the map is ready, add it to
`data/emk/functions/race/launch.mcfunction` and adjust
`data/emk/loot_tables/map.json` accordingly so that all maps will be
available.

For example, for a world with two maps, `launch.mcfunction` would
look something like this:
```
execute store result score #tmp emk-id run loot insert 1000 0 0 loot emk:map
execute if score #tmp emk-id matches 1 positioned 5000 50 0 run function emk:race/start
execute if score #tmp emk-id matches 2 positioned 10000 50 0 run function emk:race/start
```

The first line sets a random number as defined in `map.json`.
The second and third lines define two maps, one at `5000 50 0` and
another at `10000 50 0`.

To match the maximum map ID of 2, `map.json` should contain
```json
{"type":"minecraft:chest","pools":[{"rolls":1,"entries":[{"type":"minecraft:item","name":"minecraft:stone_pickaxe","functions":[{"function":"minecraft:set_count","count":{"min":1,"max":2,"type":"minecraft:uniform"}}]}]}]}
```

## The shop

The shop is not yet documented.