tic80-nightgolf/README.md

# Night Golf

## Overview

You sneak onto a golf course at night. You have a limited number of golf balls
that glow in the dark, and tees. Magically, the pins for each hole light up, but
otherwise each hole is shrouded in darkness. As you hit your ball towards the
pin, the ball lights up the course, revealing surprises and obstacles that you
interact with as you move to your next shot. Each of these events provides
narration, rewards, and more. Once you run out of glow-in-the-dark balls or
tees, or if you make yourself too known to the groundskeeper, your playtime is
over.

## Gameplay Loop

Each hole starts off shrouded in darkness, even if you've played before. At any
point while playing, the player can reference their scorecard to see what hole
they are playing, and the expected shape and hazards of the course. The player
starts at the tee-box. The player lines up their shot on the aiming screen,
proceeds to the swing screen, and then is shown the results as the ball flies
over the course, illuminating a path beneath it. Play then transitions to the
travel screen, where the player is now free to travel towards their ball. If
they venture too far outside the illuminated path, they risk getting lost or
being discovered by the groundskeeper. Then continue to hit their ball until
they finish the hole. After 9 holes, the player finishes their round of night
golf. This may change to 18 holes in the future.

## States

### Scorecard Screen

The scorecard state shows the current status of the current run, as well as the
course layout, and acts as the pause and menu screen. The player can see their
current score, see the non-obscured layout of each hole, access the save and
load system, access any in-game modifiable options, and quit the game.

### Aiming Screen

The aiming screen is a small precursor screen to the swing screen. It allows the
player to line up the direction of their shot. This screen is basically a black
rectangle, with an icon representing the player at the bottom, an icon
representing the hole/pin at the top, and a dashed line from the player
extending towards the top indicating the intended direction of hit.

### Swing Screen

The swing screen is how the player performs their hits. After lining up the show
on the aiming screen, the player now must determine first their stance at the
ball, and then the power of their swing. The stance will determine height of
shot versus distance of shot, while the power will determine the intensity of
the shot.

> For example, if hitting a ball over a hazard onto the green, the player may
> want to setup for height with high power, to safely cover the hazard, but not
> fly too far.

### Results Screen

Immediately after the player sets their stance and power, the game transitions
to an animation of the swing, and follows the ball in it's trajectory,
illuminating a path beneath it.

### Travel Screen

After the results are shown, the player is free to wander the hole as they wish.
As the move towards their ball, they will encounter events, as detailed below.
When the player arrives at their ball, they are returned to the aiming screen.

### Miscellaneous/Cutscene Screens

Unlike the other screens, these screens will be minimally or not interactive.

At each new hole, a small introduction screen may be shown, indicating the
number, the par, and maybe other relevant details about the hole.

Each event will show a screen with the details of the event and the results.

At game-over, a screen will show with details of why the game ended, which will
then drop the player to a special scorecard screen where they can see their
score, any rewards from their run, and start a new run, or otherwise interact
with the menus.

## Mechanic Specifics

### Balls and Tees

These resources could be thought of as lives. You need a ball to play, and you
need a tee to tee-off at the beginning of each hole. You may finish a hole
without a tee, but you cannot finish a hole without ball. Events during play may
give the player more tees and balls, with tees being much more common. Both tees
and balls are reusable, with tees breaking much more frequently than balls being
lost.

### Clubs

The player starts with a set of 5 clubs: 3-wood, 5-iron, 8-iron, sand wedge, and
putter. Each club has certain statistics which make it better or worse at
different shots. The exception is the putter, which can only be used on or near
the green. As the player plays the game, they may discover new clubs that add to
or improve their set of clubs.

### Swinging

The main action mechanic will be lining up and performing a hit. There are
multiple factors which contribute to a hit:
- Stance: how close the player is to the ball, and how close the club is to the
    ball. This will affect the trajectory of the ball significantly.
- Club: each club has statistics which establish and influence different results
    of a hit. These include power (minimum and maximum distance), angle (minimum
    and maximum height), and accuracy (chance to slice/hook).
- Events: certain events may add modifiers to a players swing, either for a
    certain number of swings, or for a run.
- "Charms": permanent extras that the player equips onto their bag may modify
    the players swing.

### Events

The main narration mechanic of the game is events. Events happen at every step
of the game, with some events being expected and generic (i.e., the player tees
off), but others being unexpected or unique (i.e., the player begins to tee off,
but is tackled by a swamp monster). Generally speaking, events happen during the
travel screen state, and are a way to provide rewards to the player. Some events
include:
- Finding extra tees or balls
- Finding new clubs
- Losing a ball or losing a/some tee(s)
- Gaining a temporary boon to improve your swing
- Suffering a temporary setback which degrades your swing