# Some Space Game

Top-down space ship shooter game.

It is designed to be embedded onto parent worlds & ran on virtual screens, like a mini-game.

The game is kept generic for very simple modding & customization on-the-fly via URL parameters.

The parent world can pass in UGC customization parameters directly in the URL.

## Interop
- This minigame should be able to run in any iframe anywhere that supports them. It should not **rely** on pointer lock & have good easy controls.
- Most things in it can be customized through URL parameters - but the game's Welcome Screen acts as the game's credits & should not be customized.

## Technical Input
- Prototype targets KB only.
- **Should** add touch/pointer controls & gamepad controls next.

## Gameplay
- Shoot through sequences of enemies while progressing through a level's environment.
- Collect power-ups (health, power, & bombs) from special enemy ships.
- Fight boss at the end of each level.

## Game Objects
- Player Ship
- Level's Enviornment (an MP4 or image)
- Player Bullets
- Enemy Ship
- Enemy Bullets
- Health Power-Up
- Bullet Impacts
- Ship Explosions
- Power-up Giver Enemy Ship
- Boss Ship
- Attract Screen
- Welcome Screen (Game Intro + Story Text)

## UGC Customization Parameters
| Parameter | Example Value |
|-----------|---------------|
|title| The Journey Begins |
|story| The invaders have arrived. Survive their onslaught. Defeat their boss. Save the galaxy. |
|story2| Some of the enemy has broken off and is headed towards earth. Intercept them. Save the world. |
|story3| This is the last stand. We're all counting on you. Don't give up. |
|win| Good job. But are you ready for the next level? |
|beat| The world & the galaxy are now safe... but a new challenge has emerged. |
|p1ship| https://somedomain.io/myship.glb |
|eship| https://somedomain.io/baddie.glb |
|bship| https://somedomain.io/boss.glb |
|pship| https://somedomain.io/powerupenemy.glb |
|health| https://somedomain.io/health.glb |
|lvl| https://somedomain.io/lvl1.mp4 |
|lvl2| https://somedomain.io/lvl2.mp4 |
|lvl3| https://somedomain.io/lvl3.mp4 |
|config| https://johnny.gitpages.io/config.json |

## URI-Encoded JSON Structure (Alternative to GET params.)

{
    title: <text>,
    location: <text>,
    story: <text>,
    story2: <text>,
    story3: <text>,
    win: <text>,
    beat: <text>,
    p1ship: {
        url: <glb | image>,
        pos: <text vec3>,
        rot: <text vec3>,
        scale: <number>
    },
    eship: {
        url: <glb | image>,
        pos: <text vec3>,
        rot: <text vec3>,
        scale: <number>
    },
    health: {
        url: <glb | image>,
        pos: <text vec3>,
        rot: <text vec3>,
        scale: <number>
    },
    lvl: <image | mp4 URL>,
    lvl2: <image | mp4 URL>,
    lvl3: <image | mp4 URL>
}

## High Scores Table
- High scores enter their name & the location they played from.
- High scores table shared across all instances of the game.

## Game Sequence
1. User walks up to the game's virtual screen in a parent world & interacts with it.
2. The PRESS START attract screen is shown.
3. Game's intro message is displayed, then the story text is shown.
4. Player is then dropped into the level's environment.
5. Scripted waves of enemies are dispatched as the player travels up the environment.
6. As 1 wave is defeated, the next wave is spawned, until all scripted waves are defeated & the boss is reached.
7. First boss is a carrier that shoots regular bullets & shoots out enemies.
8. Defeat the boss to see the win message.
9. Enemies get programmatically more difficult each level. Levels loop forever. When reaching the last level of a multi-level game, you see the win message.

## Game Menus
### Attract Mode
- Slate: Presented By
- Slate: Game Title/Push Start (plus subtitle from config)
- Slate: High Scores
- Cycles between these. Pressing start on Game Title leads into Intro Mode.

### Intro Mode
- Cannot be skipped.
- Show intro text & play intro music. Cannot be skipped.
- Show the level in the format of "Level a - b START" (if b is the repeated cycle > 1)
- Leads into Gameplay Mode.

### Gameplay Mode
- Fighting through hordes of enemies w/o running out of lives.
- Running out of lives leads into Game Over Mode.
- Reaching the boss leads into Boss Fight Intro Mode.

### Boss Fight Intro Mode
- Cannot be skipped.
- Shooting is disabled.
- Text appears on the screen: "BOSS INCOMING!"
- Boss enters the scene.
- Leads into Boss Fight Mode.

### Boss Fight Mode
- Shooting resumes.
- Running out of lives leads into Game Over Mode.
- Defeating the boss leads into Victory Mode.

### Victory Mode
- Cannot be skipped.
- Show victory text & play victory music.
- Victory Score Bonus Counter shown.
- If the last level of a multi-level config, leads into Ending Mode.
- Otherwise, progresses the level & leads back into Intro Mode for the next level.

### Ending Mode
- Cannot be skipped.
- Show ending text & ending music.
- Increment "repeated cycle", reset game level to 1, and lead into Intro Mode.

### Game Over Mode
- Cannot be skipped.
- Says Game Over on the screen & plays game over sound.
- If player has set a high score, it leads into Enter Your Name Mode.
- Otherwise, leads into Attract Mode (starting at High Scores slate.)

### Enter Your Name Mode
- Allows the user to set a 3-letter NAME and automatically adds the HOSTNAME of where they were playing to the data along w/ their high score & highest level achieved.
- Name entering is all done in keyboard w/ arrow keys (like an old game.)
- Leads into Attract Mode (starting at High Scores slate.)

## Developer TODO
- [ ] Add boolean app.gameRunning to main loop.
- [ ] Add Attract Mode "Press Space Bar" functionality. (Take you to title slate if not already there, or lead into Intro Mode if already on title slate.)
- [ ] Add Intro Mode sequence into Game Mode.
- [ ] Add Extra Lives system.
- [ ] Add Game Over Mode. (Save Enter Your Name mode for later.)
- [ ] Add player collision w/ enemy ships.
- [ ] Proc Level Generation/Difficulty system
- [ ] Power-Ups (guns, shoot speed, health, lives) & Power-Up Droppers
- [ ] Decide next priority: UGC system, Enter Your Name Mode.
- [ ] UGC System
- [ ] Enter Your Name Mode