
## Summary

Player is a sci-fi marine or space pirate or something
  starts with basic equipment
  finds more
  has scarce but potent upgrade opportuntities
  any weapon can be upgraded, makes a big improvement
  equipement is sort of like a tableau-builder/engine-builder game
  player has HP, game over if it goes to zero
  

Player fights robots for some reason
  robots have HP
  robots have attack behavior/attributes

In a battle the game is fun because you have tactical choices to make about what weapon to use and what to target with it

Between battles the game is fun because you have to make tricky decisions about where to invest your limited upgrades, forming a "build" that will dicatate your tactical options

Most items in the game are dual-use, giving the player more interesting choices.

The player will progress through five levels of increasing difficulty, and then either die and lose, or survive to the end and win.

If you don't get a strong enough build, you will fall behind the power curve of the game and lose.

---

## Card Nature of Game

Although the player will not interact directly with the entities in the game as "cards" they are.  They are shuffled into a deck together which randomizes the experience for each run.

Encounters consist of dealing a few cards off the deck, handling any combat with any robots, and then getting to take any items.

This deck-ness and dealing of the game may or may not be visualized to the player, either way is fine.

---

## More about equipment:

Equipment types:

- Type: Weapon (permanent)
    - Weapons are how the player attacks monsters
    - Weapons need charge to operate
    - When empty they cannot be used
    - Some weapons have the "Primary" attribute.  The player can only have one primary weapon in their tableau. Others can be in the ir inventory, but will not be available during combat.
    - The player always has a "Recharge" item that applies +1 charge to every other item, letting them be used again.  Planning for when to take this "turn off" is a tricky tactical puzzle for the player.
    - Some special weapons have limited usage: once-per-fight, or once-per-level

- Type: Gear (permanent)
    - Passive Gear: always bestows some benefit
    - Triggered Gear: activates some benefit in response to a certain event

- Type: Consumable (single-use)
    - Used once and then gone!
    - Offers a powerful effect, such as a blast of damage to all enemies, or a multi-turn stun on one enemy, or a coveted heal

## Equipment Upgrades

Every piece of equipment has an upgrade path: what it does gets better with each level of upgrade.

Every item found in the game can either be used as itself, or it can be "scrapped" and be used to upgrade another piece of gear.

This forces tough tradeoffs.  For example, should I save this powerful one-use grenade to get out of a tricky spot, or should I upgrade my gun instead?


---

## Initial setup:

Do these in order:
Shuffle 50 cards together.
Deal 5 piles of "Level" decks.
Shuffle the special "Elevator" card into the first Level deck.
Place one special "Orb" card at the bottom of each Level deck.

## Rooms

Rooms (sometimes I say "encounter") draw a few random cards from the current deck and put them face up.

The Level determines how many cards are flipped:
1 = 2 cards
2 = 3 cards
3+ = 4 cards

Robot cards vary, but many will have a "boost", most often at level 4 or 5, sometimes at 3.  The earlier their boost the less impactful, so boosts at 5 are kind of scary, but the player is ready by then.

---

## Combat

During a room, if any robots are revealed, we will go into a combat phase to battle them. The player must defeat them.  The game displays in a combat-focused mode/screen with the player's tableau at the bottom, and the robot cards left-to-right in a battle line.

Robots have HP and an attack.
In combat, they player will go first, and perform one action.

Then the robots will go in left-to-right order, executing their attack.

((IMPORTANT TECHNICAL NOTE: the game system will need time to animate the players action and the robots actions, during which time the player cannot input additional moves.  There must be a flag called something like isAnimating, which disables the player inputs, as described in dev-docs\ANIMATION.md))

This turn-exchange loop repeats until either the player loses (game over) or all robots are defeated (zero HP or otherwise removed from fight)

## Loot!

After robots are defeated, or if no robots were present in the first place, other cards flipped over are resolved.

If the elevator was present, the "Take Elevator" option is unlocked, and the player will be able to choose now or after any other encounter whether to move forward on the current level or to take the elevator to the next level.  (Cannot be done during combat)

Orb cards are not equipement - they get removed from the game but add 1 to the player's orb count (kind of like a bonus/bragging victory that shows you pushed to the end of a level)

Any equipment cards are added to the player's inventory.

Then the player is offered an equipment-management interface:

- The player can scrap any equipment in their inventory to gain an upgrade point.

- The player can spend upgrade points to upgrade equipment in their inventory

- The player can use any health-restoring consumable item

- The player can take the elevator, if unlocked on this level (by discovering the elevator card on this level)

- The player can continue moving forward on the current level (for example to push for the orb at the end)

---

# Examples

## Equipment examples

Primary Weapons
- Blaster: [2/2] Consumes 1 charge, deals 1 dmg to target monster, always fully charges when recharged at all
  - U1: +1 capacity (max charges held)
  - U2: +1 capacity
  - U3: +1 dmg

Non-Primary Weapons:
- Wide Beam: [0/3] Consumes three charge, deals 1 dmg to each robot
  - U1: +1 dmg
  - U2: +1 dmg
  - U3: +1 dmg  (upgrades are cumulative)


Consumables:
- Speed Booster: For this combat, you take an extra action on every turn
- Insta-Shell: For this combat, you take 2 less dmg from physical attacks
- Med-kit: Your health becomes 12 
  (two of this card in the game)
- Flame Grenade: 4 fire dmg to one target, 2 fire damage to all other robots

Gear:
- Charger (special - not even a card, just starting gear, cannot be scrapped, can be used as an action) - grants charge to each other piece of equipement that can hold charge and has available capacity.
 - U2: +1 charge
 - U3: +1 charge

- Battery: [1/1] Whenever another piece of equipment would spend charge, battery will spend its own charge instead, if available.  (Does not allow shields to save more HP than their current charge)
 - U1: +1 capacity
 - U1: +2 capacity

- Shields: [1/1] Whenever you would lose HP to physical or energy damage, instead lose shield charge, if available.
 - U2: +1 capacity
 - U3: shields fire damage

- Tool Kit: does nothing, but can be scrapped for 2 upgrade points


## Robot Examples

For now let's prototype with very basic shell robots:

attack (type, if not physical) / hp

flame bot: 1 fire/5
static bot: 1/5, on hit, drains 1 charge from any shield
shield bot: 2/1, plus [1/1] shield and a battery [2/2]

then make a very basic set of Robot-XYZ enemies with:
1/3
2/2
3/1
1/4
1/5

====
## TECHNICAL APPROACH

Building on a base starter kit that uses the js library boardgame.io and the plugin for it called bgio-effects.  When working on tasks that require more information about this, you can refer to dev-docs\BestPractices.md for the overall approach. I've also made the reference docs available at reference-docs\boardgamio-docs.txt

On top of this game layer, we have a React front-end.

Game has two main layers: 1. the game layer (in src\game), 2. the UI layer (mostly in src\components).  The most important design rule is to maintain the separation of these concerns.  The game layer defines the rules and controls the state of the game.  The UI layer displays that state and has user inputs (eg buttons) that let the player execute game moves.  bgio-effects provides the mechanism for the game logic to raise events which the UI code can listen to for special effects.


# IMPLEMENTATION PLAN:

- ignore, set aside, or scrap the existing project stuff from the old junk/metal game

TODO-1: build a basic combat encounter; define just enough specific cards to support that (eg blaster and charger). set up fight against two generic robots in the 1/3, 2/2, 3/1 range, give or take.
- Requires defining how equipment (weapon and gear) cards are defined.  This should be pulled out into it's own file with the understanding that this card-list is going to get large, and we should have some pattern that lets it be extensible.  But probably we don't need a full OO hierarchy.
- Also requires builing a screen and UI for the combat, including tableau interaction.
- But otherwise keep it as simple as possible.
