# RaceTracks

RaceTracks is a Fabric/Cobblemon server-side Mod that introduces Race Tracks, and racing Sessions that run on top of Tracks.

It includes:

* Track authoring and placement tools.
* Session modes: Free Run, Qualifying, and Race.
* SQLite-backed lap/session persistence.
* Leaderboards (currently layout-scoped).
* Optional PlaceholderAPI and HoloDisplays integrations.

## Requirements

Core:

* Minecraft `1.21.1` Fabric server (Arclight not tested)
* Cobblemon
* Rib (Roanoke Library Mod)

Soft Dependencies:

* PlaceholderAPI (`placeholder-api` mod): required for `%racetracks:lb ...%` placeholders.
* HoloDisplays (`holodisplays` mod): required for `/racetracks holograms ...` runtime functionality.

## Basic Concepts

### Track Layouts

* Versioned templates for a track
* Store track objects like Checkpoints, Boundaries, etc, relative to some position (similar to WorldEdit Schematics)
* Saved under `config/RaceTrack/Layouts/<layoutId>/v<version>.json`.
* Altering a track layout increments the version: leaderboards etc are scoped to a version (so if you change the track, old times don't count)

Track Layouts are used so that you can place multiple physical tracks in the world - RaceTracks is designed to allow a session to run across multiple (identical layout wise) physical tracks in the world, so you can split players.

It's also handy as they can be easily shared, copied, pasted, across different servers, without needing to be exported/imported.

### Track Instances

* Real placements of a layout in a world.
* Stores and uses absolute coordinates for track objects like Checkpoints, Boundaries, etc.
* Saved under `config/RaceTrack/Instances/<instanceId>.json`.
* Only one active session can run per instance at a time.

This is the "real track" - referred to throughout RaceTracks as an "instance". Sessions run on instances.

### Sessions

* Runtime timing engines attached to an instance.
* Modes:
  * `FREERUN`: unlimited hot laps.
  * `QUALIFYING`: unlimited laps with qualifying standings.
  * `RACE`: fixed lap-count race with finishing order.

Sessions sit on top of instances and handle timing, positioning, have results, etc.

Without a session, no timing is done, laps aren't considered.

## Docs Index

* [Commands & Permissions](https://docs.roanoke.dev/mods/mods/racetracks/commands-and-permissions)
* [Sessions Overview](https://docs.roanoke.dev/mods/mods/racetracks/sessions)
* [Free Run Session](https://docs.roanoke.dev/mods/mods/racetracks/sessions/session-freerun)
* [Qualifying Session](https://docs.roanoke.dev/mods/mods/racetracks/sessions/session-qualifying)
* [Race Session](https://docs.roanoke.dev/mods/mods/racetracks/sessions/session-race)
* [Leaderboards](https://docs.roanoke.dev/mods/mods/racetracks/leaderboards)
* [Placeholders](https://docs.roanoke.dev/mods/mods/racetracks/placeholders)
* [Holograms](https://docs.roanoke.dev/mods/mods/racetracks/holograms)
* [Storage](https://docs.roanoke.dev/mods/mods/racetracks/storage)

## Quick Start

```
/racetracks layout create <layout_id> <name...>
/racetracks instance place <layout_id> <version> [name...]
/racetracks session start <instance_id>
```

Use `/racetracks session status` to monitor active sessions.