tim.mccarthy/pirats
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add rulebook/docs

Browse Source
This commit is contained in:
Tim McCarthy
2026-06-11 14:40:33 -07:00
parent 58a7e4d4f1
commit 2af98a3eeb
4 changed files with 590 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
EXAMPLESCENE.md Normal file
View File

@@ -0,0 +1,189 @@
# Rats with Gats - Full Example Scene: The Cheesy Heist
This is a complete example of a Scene you might play out in a game of *Rats with Gats*!
For the core rules of the game, see [RULEBOOK.md](file:///Users/ttm/Projects/pirats/RULEBOOK.md).
---
## Players and their Pi-Rats
* **Gabe**: playing "Whiskey Shrinkage" (Nameless, Rank 3)
* **Sally**: playing the Deep for this scene (normally plays "Piss Whiskers")
* **Jake**: playing "Carlos" (Named, Rank 3, Captain)
---
## Setting the Scene
### Step 1: Declare Roles!
* **Gabe**: "I'll play my Pi-Rat in this scene, since I was the Deep last Scene."
* **Sally**: "I'll be the Deep this time. Piss Whiskers needs a bath, anyway."
* **Jake**: "Carlos is in! And I'm still the Captain, ya hear? So you rats better listen up!"
### Step 2: Shuffle and Draw Obstacles!
Sally returns all discarded cards to the deck and shuffles thoroughly. There's currently one Obstacle on the Obstacle List from the last scene (**7 of Hearts: Bad Breakups**). Since there's only one Deep Player (Sally) in this scene, she needs to draw cards until there are a total of two Obstacles on the list.
Sally draws from the top of the deck: **10 of Hearts: Cheese Thief**
The Obstacle List now has:
1. **7 of Hearts: Bad Breakups** (Value: 7)
2. **10 of Hearts: Cheese Thief** (Value: 10)
### Step 3: Frame the Scene!
* **Sally (Deep)**: "Alright, so you rowdy rats are in the galley below deck, drinking grog, and shootin' the breeze. The crew's been tense ever since that breakup between Salty Socks Pete and Long-Tail Lamar split everyone into factions. But NOW, someone's been stealing the cheese rations, and the crew is absolutely losing their minds about it. Pete's faction blames Lamar's, and Lamar's faction blames Pete's! You all can hear angry shouting from the deck above."
* **Gabe**: "Is there any cheese left?"
* **Sally (Deep)**: "There's one wheel of aged cheddar sitting on the galley table, guarded by a rotating shift of Pi-Rats from both factions."
* **Jake**: "Perfect. Carlos wants that cheese. That's a captain's cheese."
* **Gabe**: "I'm on it, Boss!"
---
## Playing Out the Scene!
* **Jake**: "Carlos struts into the galley, adjusting his fancy captain's hat. 'Aye, what's all this commotion about cheese, ya yeasty beasties?'"
* **Sally (Deep)**: "The two guards immediately turn on you. 'Captain! Someone's been stealin' our cheese! How could you let this happen? In this economy, no less!' They're getting pretty heated. I'm calling for a Challenge—can Carlos calm them down before this turns into a mutiny?"
### Challenge 1: Carlos Calms the Crew
#### Step 1: Establish Stakes!
* **Sally (Deep)**: "If you succeed, you calm the crew and maybe figure out who the Cheese Thief is. If you fail, the crew's anger starts growing out of control, and this could get violent."
#### Step 2: Apply Obstacles!
* **Sally (Deep)**: "I'm applying both Obstacles. The **Bad Breakups** Obstacle means half the crew won't listen to anything the other half says, and the **Cheese Thief** Obstacle represents how absolutely furious everyone is about the missing cheese. Bad Breakups is currently value 7, and Cheese Thief is value 10."
#### Step 3: Play Cards!
Jake looks at his hand: **8 of Spades**, **3 of Hearts**, **Queen of Diamonds**, **Jack of Clubs**.
* **Jake**: "Oof, that 10 is rough, but I got this. I'll play my 3 of Hearts against the Cheese Thief Obstacle, and my 8 of Spades against the Bad Breakups Obstacle."
#### Step 4: Place Cards!
Jake places his 3 of Hearts face-up in a column below the **10 of Hearts: Cheese Thief** card, rotating it 90°. He does the same with his 8 of Spades below the **7 of Hearts: Bad Breakups** card.
The Obstacle List now shows:
1. **7 of Hearts: Bad Breakups**
* *Card underneath*: 8 of Spades (rotated 90°)
* *New Value*: 8 (1 Success)
2. **10 of Hearts: Cheese Thief**
* *Card underneath*: 3 of Hearts (rotated 90°)
* *New Value*: 3 (0 Success - 3 is less than 10)
#### Step 5: Narrate Results!
* **Jake**: "Since I played Spades—Sneakin' and Schemin'—Carlos cleverly pulls aside the guards from both breakup factions and whispers to each that the OTHER side is clearly innocent. He gets them to make peace, at least temporarily. BUT, I did fail against the Cheese Thief obstacle..."
* **Sally (Deep)**: "Yeah, the crew unites under their Captain—but they also seem to be itching for some mob justice. Things could still escalate quickly!"
#### Step 6: Draw Cards!
Jake played a red card (3 of Hearts) against a red Obstacle (10 of Hearts). Since both were red, Jake draws 1 card and adds it to his hand.
* **Sally (Deep)**: "Challenge resolved! Good job. Gabe, what are you up to during this time?"
* **Gabe**: "While everyone's yelling at Carlos, I sneak toward the cheese wheel on the table, looking for clues, and maybe to steal it."
* **Sally (Deep)**: "Oh no you don't! Challenge time! Can you get close enough to examine and maybe swipe that cheese without getting caught?"
---
### Challenge 2: Whiskey Shrinkage Sneaks the Cheese
#### Step 1: Establish Stakes!
* **Sally (Deep)**: "Success means you get the cheese and some answers. Failure means you get caught red-handed and the crew knows YOU'RE the real Cheese Thief."
#### Step 2: Apply Obstacles!
* **Sally (Deep)**: "I'm only applying the Cheese Thief Obstacle. The crew's watching you like rat-hawks. Its current value is 3 (updated from the previous challenge)."
#### Step 3: Play Cards!
Gabe looks at his hand: **2 of Clubs**, **9 of Hearts**, **King of Spades**.
* **Gabe**: "I'm going all out. I'll play my King of Spades! That's a Secret Pirate Technique!"
* **Sally (Deep)**: "Nice! What is your King Technique?"
* **Gabe** (checks his Rat Records): "My Kings are... *Secret Pirate Technique #79: 'There's always a secret entrance sometimes.'* Whiskey Shrinkage doesn't even go for the cheese on the table. He knows there's a secret compartment under the floorboards where the REAL cheese stash is hidden. He pops it open and pulls out an entire log of fancy Havarti!"
* **Sally (Deep)**: "You automatically succeed!"
#### Step 4: Place Cards!
Gabe places his King of Spades in the column below the Cheese Thief Obstacle, rotating it 90°.
The Obstacle List now shows:
1. **7 of Hearts: Bad Breakups**
* *Cards underneath*: 8 of Spades (rotated 90°)
* *Value*: 8 (1 Success)
2. **10 of Hearts: Cheese Thief**
* *Cards underneath*: 3 of Hearts (rotated 90°) $\rightarrow$ King of Spades (rotated 90°)
* *New Value*: 3 (Gabe's current Rank) (1 Success - Face card value equals player's Rank)
#### Step 5: Narrate Results!
* **Gabe**: "After opening the secret compartment, Whiskey Shrinkage casually walks out of the galley with a wheel of cheese under each arm while everyone's still yelling at Carlos."
#### Step 6: Draw Cards!
Gabe played a King of Spades (Black) against an Obstacle that's Red (10 of Hearts), so he doesn't draw any cards.
* **Gabe**: "Whiskey Shrinkage is up on deck now, eating cheese openly. He's taunting the crew with it, hoping to draw out the Cheese Thief. 'Will the owner of this delicious havarti come to the lost and found?' I'll make sure everyone can see me, too."
* **Sally (Deep)**: "Uh oh! Crew members from across the deck take notice, and everyone is looking around to see who steps up for the cheese! Just as it seems no one is willing to accept ownership, a Pi-Rat jumps down from the crow's nest with her knives drawn, and barrels down on Whiskey Shrinkage. Challenge time!"
---
### Challenge 3: The Crows Nest Confrontation
#### Step 1: Establish Stakes!
* **Sally (Deep)**: "If you succeed, you fight off the Cheese Thief and keep the cheese you found. If you fail, the Cheese Thief beats you up and accuses you of being the mastermind behind the cheese theft."
#### Step 2: Apply Obstacles!
* **Sally (Deep)**: "I'm applying the **Cheese Thief** Obstacle again—they're absolutely enraged. Its current value is 3. I'm also applying the **Bad Breakups** Obstacle again, since tensions are so high right now. Its current value is 8."
* **Jake (Captain)**: "Wait! I want to help! Can Carlos assist?"
* **Sally (Deep)**: "Sure! You can play a card against one of the Obstacles applied to the Challenge."
#### Step 3: Play Cards!
* **Gabe**: "I'll play my 9 of Hearts against the Cheese Thief Obstacle. That beats the 3!"
* **Jake**: "And I'll play my Queen of Hearts against the Bad Breakups Obstacle to help out. That's my *'when in doubt, flirt your way out!'* Secret Pirate Technique, which automatically beats the Bad Breakups Obstacle value of 8."
#### Step 4: Place Cards!
Gabe places his 9 of Hearts below the Cheese Thief Obstacle. Jake places their Queen of Hearts below the Bad Breakups Obstacle.
The Obstacle List now shows:
1. **7 of Hearts: Bad Breakups**
* *Cards underneath*: 8 of Spades (rotated 90°) $\rightarrow$ Queen of Hearts (rotated 90°)
* *New Value*: Rank (Jake's Rank of 3) (2 Successes)
2. **10 of Hearts: Cheese Thief**
* *Cards underneath*: 3 of Hearts (rotated 90°) $\rightarrow$ King of Spades (rotated 90°) $\rightarrow$ 9 of Hearts (rotated 90°)
* *New Value*: 9 (2 Successes)
#### Step 5: Narrate Results!
* **Gabe**: "I played Hearts—Shoutin' and Singin'—so Whiskey Shrinkage starts singing a sea shanty about cheese so beautiful and ridiculous that the sailors stop in their tracks, mesmerized!"
* **Jake**: "Carlos joins in with a sexy rat dance, and does their best to give off 'hot captain' vibes."
* **Sally (Deep)**: "Weird, but whatever. You both share in the success—the cheese is safe, and the original culprit puts her knives away and surrenders to the crew. 'I would have gotten away with it too if it wasn't for your stupid musical number!' the Cheese Thief says."
#### Step 6: Draw Cards!
* Gabe played a 9 of Hearts (Red) against a red Obstacle, so he draws 1 card.
* Jake played a Queen of Hearts (Red) against a red Obstacle, so he would draw 1 card, but because he was assisting, he does *not* draw.
---
## Ending the Scene
* **Sally (Deep)**: "Alright, let's check the requirements for ending the Scene. Both Pi-Rat Players have been challenged at least once. Has anyone made progress on their Objectives?"
* **Gabe**: "Whiskey Shrinkage doesn't have a real name yet, but maybe I earned one with my clever detective skills and singing?"
* **Sally (Deep)**: "Sure, but I don't know if that was name-worthy. We can always have a vote to see if you completed this Objective, if you'd like?"
* **Gabe**: "Yeah, let's do it! Who thinks I earned a real Pirate name and completed my second Personal Objective?"
* **Sally (Deep)**: "I vote yes."
* **Jake**: "Same here!"
* **Gabe**: "Well, I'm definitely voting in favor of myself!"
* **Sally (Deep)**: "It looks like you got a name! What is it?"
* **Gabe**: "You can call me… **Tim**."
* **Sally (Deep)**: "Yeah, yeah, alright 'Tim'. Make sure to write down your new name and mark off that you completed your second Objective. What about Jake?"
* **Jake**: "Carlos is the Captain, so that's Crew Objective 2 already completed. And we control the ship, so Crew Objective 1 is done. But we haven't committed any piracy yet. I don't think I completed any Personal Objectives during this Scene, but I did my duties as Captain!"
* **Gabe**: "Agreed!"
* **Sally (Deep)**: "Fair enough. And we still have both Obstacles on the list, so they're not cleared, but both are close to being discarded (2 successes each, in a 3-player game they need 3 successes to be discarded). I think there's more story here. But actually, I'm going to end the scene here anyway. This was a good warm-up Scene! You rats have had enough fun for now, and we can always come back to this cheese situation later."
* **Jake**: "Okay!"
* **Gabe**: "Sounds good!"
---
## Between Scenes
### Step 1: Pirate Ranking (Voting)
* **Gabe**: "I vote for Carlos. They stepped up to defend me when it could have gone really bad."
* **Jake**: "I vote for Whiskey Shrinkage—sorry, I mean Tim. That Secret Pirate Technique with the hidden cheese was amazing."
* **Sally**: "I'm giving my vote to Gabe as well. Tim gets a Rank!"
* *Tim's Rank increases from 3 to 4.* (Updated in Rat Records)
### Step 2: Additional Rank Bonuses
Gabe completed his second Personal Objective too, so he increases his Rank again, putting him at **5**! Tim is now tied with Carlos for the highest-ranking Pi-Rat, which means Gabe's Hand size increases by 1 (to 4 cards). Because his Hand size increased, Gabe immediately draws a card from the deck.
### Step 3: Deep Players Draw Cards
Sally was the Deep, so she may discard any cards in her hand, and then draws back up to her maximum Hand size, which is now **2** (since she has the lowest Rank of all Pi-Rats, at Rank 2).
### Step 4: Start a New Scene!
* **Sally**: "Okay, next scene! Let's see what other chaos these rats get into..."
*(Someone shuffles the deck and everyone prepares for the next scene.)*

92
OBSTACLES.md Normal file
View File

@@ -0,0 +1,92 @@
# Rats with Gats - Obstacle Type Charts
This file contains the full list of Obstacle Type Charts for *Rats with Gats*, categorized by card suit. During the game, when the Deep draws an Obstacle card, its suit and value determine which threat from these tables is introduced.
For the core rules of the game, see [RULEBOOK.md](file:///Users/ttm/Projects/pirats/RULEBOOK.md).
---
## Clubs: Unwanted Passengers
These types of Obstacles represent unexpected visitors, stowaways, and boarding parties.
| Card | Name | Description |
| :---: | :--- | :--- |
| **A** | **Animal Stowaways** | Octopuses, seagulls, and lobsters infiltrating the crew, pretending they belong while being terrible at their jobs! |
| **2** | **Squidfolk Fisherman** | Confused passenger who thinks this is a merchant vessel looking to buy his daily catch. He is quite insistent! |
| **3** | **Goblin Research Team** | These interstellar beings like to conduct invasive studies all across Yeld. For whatever reason, the Pi-Rats have captured the Goblins' attention, and now they won't leave the ship alone! At least the goblins are mostly harmless, even if they are annoying and constantly in the way with their invasive probing. |
| **4** | **Fairy Deserter** | Deserter from an enemy vessel seeking asylum. No one trusts a deserter, but Fairies are almost five times the size of a Pi-Rat. It might be best to play nice! |
| **5** | **Loitering Mermaid** | Mermaids love to hitch rides on unsuspecting ships, drinking all the booze, smoking all the cigarettes, and starting all kinds of drama among the crew. Some Mermaids do this professionally as saboteurs, while others simply do it for the love of the game. |
| **6** | **Mergang** | A group of Mermaid Privateers have emerged from the ocean below to board the ship in a good old-fashioned robbery. While these Mermaids aren't necessarily out for blood, they are highly trained in naval combat and won't back down easily! |
| **7** | **Lustful Bean Whale** | A giant, magical whale made of beans! The creature seems to have mistaken the ship for a potential mate. If the Bean Whale gets too frisky, its massive body could do some real damage to the ship! |
| **8** | **Nautical Knights** | Oh Shit, it's the feds! A band of Vampire Knights loyal to the Kingdom of Yeld have snuck aboard somehow and are slaughtering everyone on the ship. It's every Rat for themselves! |
| **9** | **Deep Mage Fleet Inquisitor** | Deep Mages are powerful spell casters who work directly for the oceanic god hidden below the waves. This Deep Mage is currently inspecting and investigating all seafaring vessels in the area, looking for traitors, turncoats, and spies working directly against the Deep. It's probably best to cooperate and hope we get a pass! |
| **10** | **Pi-Rat Commodore** | A Pi-Rat commodore has come to claim the ship as one of their own by out-pirating the current Captain. We can't let ourselves be absorbed into some other rat's crew! |
| **J** | **Annoying Sailor** | Ship's previous crewmember who wants their bunk back, and maybe some revenge. |
| **Q** | **Bossy First Mate** | Ship's previous first mate still trying to give orders. The problem is some of the crew keep listening to 'em! |
| **K** | **Vengeful Captain** | Ship's previous Captain who refuses to let go, and keeps challenging the current Captain for control of the ship. |
> [!NOTE]
> **Ghosts**: Sometimes the Pi-Rats must face an unwanted passenger again, even if they had killed them in a previous Scene. When this happens, the unwanted passenger will return as a ghost, haunting the crew in obstructive ways and creating challenges like any other Obstacle would.
---
## Spades: Oceanic Occurrences
These types of Obstacles represent environmental dangers and external threats from the sea.
| Card | Name | Description |
| :---: | :--- | :--- |
| **A** | **Freaky Fog** | Heavy fog has reduced visibility to almost nothing, and the crew is a little spooked. Everyone should be extra careful! |
| **2** | **Dead Seas** | A strange, ghostly stillness and silence claims the area. No waves, no wind, no life to be found. The living shouldn't stay here for long! |
| **3** | **Secret Reefs** | Dangerous shallow waters and secret reefs hide who knows what else. Navigating this will be difficult! |
| **4** | **Deep Legion Blockade** | A blockade of Deep Legion Ships has cut off our route. They may want to come aboard to perform an inspection before we can pass. Better be on our best behavior! |
| **5** | **Pirate Hideout** | A secret pirate island happens to be nearby. Crews from all over come to drink, relax, and swap tales with each other. Sometimes a fight breaks out, but most pirates end up surviving it, so no hard feelings! |
| **6** | **Wicked Whirlpool** | A Whirlpool of epic proportions has captured every vessel in the area, sending everyone spiraling. The Whirlpool threatens to pull the ship down, along with everything else. Is it natural, or is there something else going on? |
| **7** | **Floating Fairy Fortress** | Fairy sailors working for the Vampire Prince have built a massive fortress that floats off the Kingdom's coastline. The fortress has decimated Legion ships for a season, and most pirates have fled the area. If any Fairy scouts spot us we'll have a nasty cannon battle on our hands! |
| **8** | **Frozen Fury** | A brutal blizzard has covered the sea in freezing rain and thick snow, and crew members are freezing in place across the ship. Worst still, hidden icebergs have been spotted nearby! |
| **9** | **Hurricane Havoc** | A massive and deadly storm comes rolling in. The wind and rain beats the ship from all sides as the waves throw it every which way. Secure the cargo! Batten down the hatches! Get below deck! |
| **10** | **Ship-wrecker Queen's Graveyard** | A colossal, Kaiju-sized Mermaid known as a Shipwrecker Queen has made a hunting grounds out of the area. In her wake is an endless graveyard of ships, stacked and strewn across the sea. Each ship in the graveyard was torn apart by the hands of the massive Mermaid, as she scoured the vessels for any tasty crew to eat. Don't let her see us, or we'll be next! |
| **J** | **Fish Storm** | The ship is being pursued by a magic fish storm. Aquatic life of all shapes and sizes rain down from the clouds above, and they seem just as upset about it as we are! |
| **Q** | **Mysterious Pursuers** | The ship is being chased by an unknown vessel. It seems to keep its distance, but may retaliate if provoked. Who could it be? |
| **K** | **Cursed Island** | A strange island keeps appearing before the ship, no matter the direction we sail in. Almost every crewmember says they've had strange dreams about the island for days, and a few have even claimed to have heard whispers and voices beckoning the crew to investigate. We need answers! |
---
## Hearts: Pi-Rat Problems
These types of Obstacles represent internal crew conflicts and personal issues.
| Card | Name | Description |
| :---: | :--- | :--- |
| **A** | **Over Served** | Everyone got really drunk on the job. This isn't really a problem for Pi-Rats. |
| **2** | **Pirate Flu** | There's a bug going around the ship and everyone calling in sick to work! |
| **3** | **Tail Measuring Contest** | A tail measuring contest has led to some major Gat Envy amongst the crew! Everybody is in their feelings about it, and petty arguments have broken out several times. |
| **4** | **Gambling Problems** | The Pi-Rats have been gambling over everything and it's starting to cause tension and debt. Crew members have lost all their possessions, and there's even been talk about "collecting kidneys" next. There's only one way out for those in debt: More gambling! |
| **5** | **Scurvy** | The scourge of the seas! Scurvy has taken down many a Pi-Rat, and now it's come for the crew. There are few things more dramatic than a Pi-Rat who thinks they are dying of Scurvy. |
| **6** | **Doldrums** | A wave of depression has hit the crew, and everyone's feeling pretty down right now. What's even the point, ya'know? |
| **7** | **Bad Breakups** | A lover's quarrel has divided the crew! Everyone has to choose a side, and it's going to be really awkward for a while. |
| **8** | **Crew Wedding** | Members of the crew are getting married! Everyone is trying to juggle their pirate duties with their wedding duties, and nothing is going right. |
| **9** | **Double Down Dares** | A series of escalating pirate dares among the crew has gotten completely out of hand. If this keeps going, someone's going to get shot on purpose, or worse, sink the ship! |
| **10** | **Cheese Thief** | Someone has been stealing cheese, and now everyone is livid. Crimes like these are too important to let slide. Everyone stop what you're doing! The culprit must be found, and immediately dealt with... Pi-Rat style. |
| **J** | **Super-duper-stitious** | The crew has grown superstitious as of late, and morale has taken a dive. Only more superstition can save us! |
| **Q** | **Pirate Curse** | The crew has been magically cursed by some unknown thing. There has to be some kind of complicated or convoluted way of breaking it! |
| **K** | **Among us** | Someone on the ship is a traitor, and everyone is suspicious of everyone else. The traitor must be found before they can sell us out to our enemies! |
---
## Diamonds: Ship Troubles
These types of Obstacles represent damage and malfunctions affecting the vessel.
| Card | Name | Description |
| :---: | :--- | :--- |
| **A** | **Rat Bastards** | Regular rats have eaten through the cargo, destroying, devouring, and defecating on everything below deck. It's a real mess! |
| **2** | **Slip and Slide** | The deck has been freshly swabbed, but the crew used slippery soap to do it. Those fools! Now everyone is sliding around. Some have even slipped overboard! |
| **3** | **Broken Straps** | Loose cargo has broken from its secured position and is rolling around dangerously all over the ship. The cargo must be collected and tied back down before it's lost or someone gets squished! |
| **4** | **Low Supplies** | The ship is running low on the essentials: alcohol, tobacco, fresh water, and food (in that order). If we don't get some supplies soon we'll have a bunch of starving, cranky, and sober mutineers on board! |
| **5** | **Torn Sails** | The sails have been badly shredded, slowing the ship's max speed significantly. These sails will need to be patched or replaced! |
| **6** | **Jammed Helm and Rudder** | Something has jammed or damaged the rudder (rutter) and now the helm won't budge. We can't change course! |
| **7** | **Stuck Anchor** | The anchor won't lower or raise. Either it's stuck somewhere on the reefs, wreckage, or seabed, or it won't deploy at all, causing the ship to drift in the wind and waves! |
| **8** | **Broken Bilge Pump** | The bilge pump has failed and the ship has begun taking on too much water. Somebody get some buckets before we sink! |
| **9** | **Severed Mast** | The main mast has been heavily damaged, compromising the rigging and sails. The ship isn't going anywhere now! |
| **10** | **Powder Bomb** | The ship's stockpile of ammunition and explosives has detonated, causing massive damage and starting several large fires. Some of the crew have already fled, but the ship can still be saved if everyone works together! |
| **J** | **Mystery Leak** | Somewhere on board is a leak, and no one can seem to find it. Maybe it's random magical phenomena, or maybe it's something more nefarious? If the leak isn't dealt with, we're all going to wake up underwater! |
| **Q** | **Bad Navigation** | Incorrect navigational charts and bad directions have sent the ship way off course and into stranger seas. Where are we, and where do we go from here? |
| **K** | **It's Alive** | The ship is brought to life through magical means. It's not going to cooperate without an incentive, now that it has its own wants and needs. |

309
RULEBOOK.md Normal file
View File

@@ -0,0 +1,309 @@
# Rats with Gats: A Story Game about the Pi-Rats of Yeld!
**Written & Designed by**: Nick Smith
**Art by**: J. Richmond
**Yeld Team**: Sally Hsu (Producer), Maia and EmmaVoid (Support)
*Copyright 2025 Nick Smith and J. Richmond. The Magical Land of Yeld is a product of Yeld LLC.*
Welcome to **Rats with Gats**, a collaborative storytelling game about ordinary stowaway rats onboard a ship who are transformed into gunslinging Pi-Rat pirates through the radical power of Math Magic!
---
## Quick Reference Links
* [OBSTACLES.md](file:///Users/ttm/Projects/pirats/OBSTACLES.md) - Tables of Obstacle Types by suit (Clubs, Spades, Hearts, Diamonds)
* [EXAMPLESCENE.md](file:///Users/ttm/Projects/pirats/EXAMPLESCENE.md) - Full walkthrough of a play scene ("The Cheesy Heist")
---
# Table of Contents
1. [Part 1: Introduction](#part-1-introduction)
2. [Part 2: Creating a Pi-Rat](#part-2-creating-a-pi-rat)
* [Rank and Hand Size](#rank-and-hand-size)
* [Secret Pirate Techniques](#secret-pirate-techniques)
* [Objectives](#objectives)
* [Personal Objectives](#personal-objectives) (Gat & Name Privileges/Taxes)
* [Crew Objectives](#crew-objectives) (Captain rules)
3. [Part 3: Playing The Game](#part-3-playing-the-game)
* [Setting Scenes](#setting-scenes)
* [Playing Out a Scene](#playing-out-a-scene)
* [Ending a Scene](#ending-a-scene)
* [Between Scenes](#between-scenes)
* [Resolving Challenges](#resolving-challenges)
* [Using Face Cards & Jokers](#using-face-cards-jokers)
* [Advanced Resolution Mechanics & Questions](#advanced-resolution-mechanics-questions)
4. [Part 4: Setting Information](#part-4-setting-information)
5. [Final Thoughts](#final-thoughts)
---
# Part 1: Introduction
What Are Pi-Rats?
Pi-Rats are four-foot-tall, gun-toting, ship-stealing rodents created by accident during a long naval war between the Kingdom of Yeld and the Legions of the Deep. Pi-Rats were originally designed to be weapons—disposable soldiers who could overwhelm enemy crews. Instead, they became something far more dangerous: pirates with attitude, cunning, and an unshakeable love of violence and the sea. Pi-Rats are scrappy, loyal to their crews, and almost never die of old age (mostly because they rarely survive that long).
Your Story Begins
You and your fellow players are ordinary rats—stowaways hiding in the cargo hold of a ship sailing the dangerous waters of Yeld. But when an unknown Mathematical mage casts the “Pie” spell, everything changes. You’re suddenly bigger, smarter, and armed with an overwhelming urge to commit piracy. You’re now a Pi-Rat!
Your first order of business? Steal the ship you’re on. Deal with the current crew, establish control, and make it yours. From there, the real adventure begins: choosing a captain, assembling your crew, and committing enough piracy to earn your place in Pi-Rat legend.
The World Of Yeld
Yeld is a vast and dangerous fantasy world—a place of magic, monsters, and mystery. The oceans are controlled by the Deep, an ancient oceanic god who wages eternal war against the Vampire Prince Dragul and his Fairy armies, who rule the Kingdom of Yeld. Pi-Rats exist in the chaos between these powers, stealing ships from both sides and carving out their own chaotic existence on the high seas. Expect to encounter Mermaids, Squidfolk, vengeful ghosts, magical storms, rival pirates, and the occasional Bean Whale who’s fallen in love with your ship.
### What Do I Need To Play?
* **3–6 Players** with a strong enthusiasm for whimsical piracy or rodentia.
* **A standard deck of playing cards** with both Jokers still in there.
* **A couple sheets of paper, some note cards, and at least 1 pencil** for tracking Objectives, Pi-Rats (Rat Records), and Secret Pirate Techniques.
### Summary Of Play
1. Each Player creates a Pi-Rat crewmember and 3 Secret Pirate Techniques.
2. As a group, take turns setting scenes where some Players control their Pi-Rats while others play as the Deep.
3. During each scene, participating Pi-Rat Players attempt to complete Personal and/or Crew Objectives.
4. Deep Players draw Obstacle cards and challenge the Pi-Rats.
5. Pi-Rats play cards from their Hand to overcome Obstacles.
6. A scene ends when all Pi-Rats have fled or the Deep chooses to end it.
7. Between scenes, Players vote to Rank up crew members and rotate roles.
---
# Part 2: Creating a Pi-Rat
To create a Pi-Rat, answer the following 6 questions and record them on a sheet of paper (your **Rat Records**). Go with your gat!
1. **What does your Pi-Rat look like?** Pi-Rats look very similar to one another, but distinguish themselves with bandanas, eyepatches, clothing, scars, tattoos, or body paint.
2. **What does your Pi-Rat smell like?** Pi-Rats identify each other by scent. Before receiving a proper name, they are referred to by the smells they produce.
3. **What was the first thing your Pi-Rat said after transforming?** A Pi-Rat’s first words indicate their pirate personality.
4. **Is your Pi-Rat good at Math?** This has no implications or meaning.
5. **What is something other pirates like about your Pi-Rat?** Let another Player answer this question for you.
6. **What is something other pirates hate about your Pi-Rat?** Let another Player answer this question for you.
*(Don’t worry about a name right now; that comes later!)*
### Determine Starting Rank
Once questions are answered, randomly determine each Player's starting Rank:
* **One Player** starts at **Rank 3**. This Player must play the **Deep** during the first scene of the game.
* **One Player** starts at **Rank 1**. This Player must play their **Pi-Rat** during the first scene.
* **All remaining Players** start at **Rank 2**. These Players may choose to play either their Pi-Rat or the Deep during the first scene.
---
## Rank and Hand Size
Your Rank represents your status and reputation. The higher your Rank, the more respected you are. Pi-Rats gain Ranks as follows:
* Complete your first Personal Objective $\rightarrow$ **Gain 1 Rank**
* Complete your second Personal Objective $\rightarrow$ **Gain 1 Rank**
* Complete your third Personal Objective $\rightarrow$ **Choose another Pi-Rat to gain 1 Rank**
* Receive the most votes during Between Scene voting $\rightarrow$ **Gain 1 Rank**
* Special circumstances determined by the group $\rightarrow$ **Gain 1 Rank**
Your Hand size determines how many cards you have available for Challenges. Compare Ranks to determine Hand Sizes:
| Rank Placement | Maximum Hand Size |
| :--- | :---: |
| **Highest Rank Pi-Rat(s)** | 4 cards |
| **Middle Rank Pi-Rat(s)** | 3 cards |
| **Lowest Rank Pi-Rat(s)** | 2 cards |
> [!IMPORTANT]
> Anytime your Hand size increases, you immediately draw a card and add it to your Hand. This may happen in the middle of a Scene.
---
## Secret Pirate Techniques
Any time a Pi-Rat Player plays a Face Card (Jack, Queen, King) when resolving a Challenge, that Challenge is resolved utilizing a **Secret Pirate Technique**! These represent special moves, tricks, or cartoon logic.
**Example Techniques:**
* *Secret Pirate Technique #64*: "I missed on purpose"
* *Secret Pirate Technique #3*: "Carlos will figure it out"
* *Secret Pirate Technique #57*: "Never trust a hatless captain"
* *Secret Pirate Technique #90*: "I'm not left handed"
* *Secret Pirate Technique #15*: "The Albatross is always watching"
* *Secret Pirate Technique #99*: "I've got a bomb"
#### Technique Creation & Assignment
1. Using individual note cards, each Player writes down the names of 3 Secret Pirate Techniques.
2. Once created, Players swap those techniques, one at a time, with other Players until they have 3 new techniques created by others.
3. Write these 3 Techniques in your Rat Records.
4. Assign each of the 3 Techniques to a different Face Card type (**Jack, Queen, King**). Playing that Face Card type activates that specific Technique, allowing you to narrate a spectacular, automatic success!
---
## Objectives
Objectives guide your actions. Always consult them for inspiration during a scene.
### Personal Objectives
Must be completed in order:
1. **Get a Gat (or something just as good)**: Acquire an impressive weapon (pistol, cutlass, etc.).
* **Gat Privileges**: While you have a Gat, Black cards you play (Clubs ♣ and Spades ♠) during Challenges have their Value increased by 1.
* **Gat Tax**: When a Gatless Pi-Rat faces a Challenge, they may ask a Pi-Rat with a Gat in the same Scene to attempt it for them.
* *If accepted*: The Gatless Pi-Rat gives the Gatted Pi-Rat one random card from their Hand (the Gatted player chooses without looking). The Gatted Pi-Rat attempts the Challenge, sharing the successes and failures.
* *If refused*: The Gatted Pi-Rat must hand over their Gat to the Gatless Pi-Rat (who immediately completes Personal Objective 1). The newly Gatted Pi-Rat attempts the Challenge. If they succeed, they keep the Gat (the original owner must find a new one). If they fail, they return the Gat and cannot initiate a Gat/Name Tax for the rest of the Scene.
2. **Earn a Name (a normal one is fine)**: Gain a proper pirate name (e.g., Carlos, Barry, Jaspar) instead of temporary crew nicknames (e.g., Piss Whiskers, Dainty Spanker).
* **Name Privileges**: While you have a Name, Red cards you play (Diamonds ♦ and Hearts ♥) during Challenges have their Value increased by 1.
* **Name Tax**: When a Pi-Rat with a Gat but no Name faces a Challenge, they may ask a Named Pi-Rat in the same Scene to attempt it for them.
* *If accepted*: The Nameless Pi-Rat gives the Named Pi-Rat one random card from their Hand. The Named Pi-Rat attempts the Challenge, sharing successes/failures.
* *If refused*: The Named Pi-Rat gives their Name to the Nameless Pi-Rat (who immediately completes Personal Objective 2). The newly Named Pi-Rat attempts the Challenge. If they succeed, they keep the Name. If they fail, they return the Name and cannot initiate a Gat/Name Tax for the rest of the Scene.
3. **Die Like a Pirate (some pirates retire instead; those pirates are smarter than you)**: Go out in a blaze of glory or retire honorably.
### Crew Objectives
Must be completed in order:
1. **Steal a Ship (the one we're on right now is a good choice)**: Take control of a vessel by dealing with the crew.
2. **Choose a Captain**: Establish a leader.
3. **Commit Piracy**: Plunder, raid, bury treasure, and build your reputation.
#### Pi-Rat Captain Rules
* **Becoming Captain**: Once the crew controls a ship, the highest-Ranked Pi-Rat becomes the de facto Captain. Any Pi-Rat can Challenge for leadership at any time during a scene if both are present. The Captain remains in power until they give up the position, are defeated in a challenge, die, or the ship is lost.
* **Captain Privileges**: The Captain's Hand size is increased by +1, regardless of Rank. The Captain has the final say in all ship/crew disputes, and wins ties in crew votes.
* **Captain Tax**: Being Captain is high pressure! Captains lose 1 Rank each time they personally fail a Challenge during a scene.
---
# Part 3: Playing The Game
## Setting Scenes
Before each Scene, complete these setup steps:
1. **Declare Roles!** Players announce their role: **Pi-Rat Players** (control characters) or **Deep Players** (control environment, threats, NPCs). There must be at least 1 of each per scene. Players who were Deep in the previous scene must play Pi-Rats in the next.
2. **Shuffle and Draw Obstacles!** Return discards to the deck and shuffle. Draw cards from the top and add them to the **Obstacle List** until the total is **at least one greater than the number of Deep Players** in the scene.
3. **Frame the Scene!** Deep Players collaboratively describe the location, situation, and how the drawn Obstacles manifest as an urgent problem.
> [!NOTE]
> **First Scene Setup**: The first scene must establish that the Pi-Rats are on a ship they can steal (or have immediate opportunity to do so). Do not start far from water.
---
## Playing Out a Scene
* **Pi-Rat Players** narrate actions, roleplay, make decisions, and play cards to overcome Obstacles.
* **Deep Players** control NPCs, hazards, enemies, and call for Challenges when Pi-Rats attempt something risky. Deep Players can distribute the Obstacles among themselves or share them.
---
## Ending a Scene
Deep Players choose when to end a Scene. Minimum requirements to end a Scene:
* Each participating Pi-Rat has been challenged at least once and had a chance to progress an Objective.
* OR there are no Obstacles remaining on the Obstacle List.
* OR all Pi-Rat Players have fled or been narratively incapacitated (death, capture, etc.).
---
## Between Scenes
Upkeep steps before starting a new Scene:
1. **Pirate Ranking (Voting)**: Each Player nominates one *other* Pi-Rat Player to Rank up. The player with the most votes gains 1 Rank. Ties are resolved by discussion or random choice. Deep Players from the previous scene cannot be nominated but may vote.
2. **Additional Rank Bonuses**: Apply Ranks for completed Personal Objectives.
3. **Deep Players Draw Cards**: Players who were Deep in the previous scene may discard any number of cards, then draw back up to their maximum Hand size (based on their Rank).
4. **Start a New Scene!** Repeat setup.
---
## Ending the Game
End the story when the group feels ready. For the best experience, ensure:
* Each player has played the Deep at least once.
* Each Pi-Rat has completed at least one Personal Objective.
* The crew has completed all 3 Crew Objectives.
* *Recommended*: Include a wrap-up scene where the Pi-Rats party til they pass out in a pile.
---
# Resolving Challenges
When a Deep Player calls for a Challenge, follow these steps:
### Step 1: Establish Stakes!
Deep Players explain what success and failure mean.
### Step 2: Apply Obstacles!
Deep Players apply one or more cards from the **Obstacle List** to the challenge. (See [OBSTACLES.md](file:///Users/ttm/Projects/pirats/OBSTACLES.md) for the suit/value meanings).
### Step 3: Play Cards!
The Pi-Rat Player plays one card from their Hand for each applied Obstacle.
* **Card Beats Obstacle Value**: Success!
* **Card is Equal to or Lower than Obstacle Value (or no card played)**: Failure!
* *Note*: If multiple Obstacles are applied, you only need to succeed at one to pass the Challenge, but each failed Obstacle creates a narrative complication.
#### Card Values:
* **Numbers (2–10)**: Face value.
* **Aces**: Value of 1.
* **Face Cards (J, Q, K)**: When played by a Pi-Rat, activates a Secret Pirate Technique (automatic success). When acting as an Obstacle, their value equals the Rank of the challenged Pi-Rat.
### Step 4: Place Cards!
Played cards are placed face up below the applied Obstacle card and rotated 90°. **The last played card in the column determines the Obstacle's new value for future challenges.** The original Obstacle card always determines the suit color and narrative chart entry.
### Step 5: Narrate Results!
The suit of the card played to successfully beat an Obstacle determines how the Pi-Rat overcomes it:
* **♣ Clubs - Shootin' and Stabbin'**: You use violence, combat, or direct confrontation.
* **♦ Diamonds - Swimmin' and Sailin'**: You use nautical skills, athletics, or mobility.
* **♠ Spades - Sneakin' and Schemin'**: You use stealth, deception, or cunning plans.
* **♥ Hearts - Shoutin' and Singin'**: You use social skills, performance, or charisma.
*(If you play a Face Card, narrate using the name of your Secret Pirate Technique instead).*
### Step 6: Draw Cards!
Draw 1 card back into your Hand for each card you played that **matched the suit color** (Red/Black) of the original Obstacle card.
---
# Using Face Cards & Jokers
### Jacks, Queens, and Kings
* **Played by a Pi-Rat**: Triggers a assigned Secret Pirate Technique. **Automatic success** regardless of the Obstacle value. Describe the ridiculous trick in action.
* **Drawn as or placed below an Obstacle**: The value of the card is equal to the **Rank** of the challenged Pi-Rat.
### Jokers (Pirate Luck)
* **Played by a Pi-Rat**: Play at any time (before or after a challenge) to discard one Obstacle from the list entirely (along with its column) and draw a new one. The Joker is then discarded.
* **Drawn as an Obstacle**: Discard the Joker immediately, and permanently increase the number of Obstacles required on the list for the following scene by 1.
---
# Advanced Resolution Mechanics & Questions
* **Can the Deep say no?** Yes. Deep Players can veto impossible or context-breaking actions without offering a challenge.
* **Can multiple Pi-Rats attempt the same Challenge?** Yes. Other participating Pi-Rats can play their own cards against the applied Obstacles on behalf of the challenged Pi-Rat. They narrate their assistance and share in the successes and failures, but **only the originally challenged Pi-Rat draws cards** in Step 6.
* **Can Pi-Rats Challenge each other?** Yes. The challenging Pi-Rat plays 1 card from their hand face up as a temporary Obstacle (narrating based on suit). The defender plays a card against it. Resolve normally. Afterward, discard the temporary Obstacle and cards below it. Only the defender draws cards in Step 6.
* **How do we get rid of Obstacles?** Once an Obstacle has been successfully beaten a number of times **equal to the total number of players**, it is discarded. Unbeaten or partially beaten Obstacles remain on the list across scenes.
* **Can my Pi-Rat flee from a Scene?** Yes, anytime before or after a Challenge. Fleeing Pi-Rats cannot participate until the next Scene and cannot progress Objectives.
* **What do we do with discarded cards?** Place them in the discard pile. They are shuffled back into the deck during Step 2 of Setting Scenes.
* **What happens when my Pi-Rat dies, retires, or is kicked out?** Your story arc is complete! Create a new Rank 1 recruit with new random techniques and fresh objectives. Alternatively, you can play your deceased Pi-Rat as a **Ghost** (unable to interact well with the living but still helpful).
* **What happens when our ship sinks?** Stealing a new ship becomes the immediate priority. The Pi-Rats might wash up on an island, get rescued (and steal the rescue ship), build a raft, or escape capture.
---
# Part 4: Setting Information
The Magical Land of Yeld
Built on the back of a slumbering Serpent God, Yeld is a mysterious fantasy land bordered by dangerous wildlands. The Fairies claim to be the oldest inhabitants, but even they do not know all its secrets. It is a land of ruins, magic, monsters, and varied climates (mountains, swamps, deserts, forests, and frozen tundras).
The Vampire Prince, Dragul
Dragul usurped control of Yeld nearly 500 years ago with the help of Fairies from the Fairy Lands. A civil war crushed resistance and spread undeath. Centuries later, the oceanic god (the Deep) sent its legions of Mermaids and Squidfolk to eradicate Dragul and the undead, resulting in an ongoing war on land and sea.
The Deep
The Deep is an ancient oceanic god who detests Prince Dragul and undeath. It created species like Mermaids and Squidfolk to act as commanders and soldiers in its legions.
The Pi-Rats of Yeld
Created during the war when Goblin Math Divers cast the spell "Pie" (a spell of recited numbers that transforms stowaway rats into giant, clever gunslinging rodents to overwhelm enemy crews). The Pi-Rats proved too clever, learned to sail and speak, and stole so many ships they temporarily ground the war to a halt! They have a reputation for chaos, violence, and loyalty. There are 43 traditionally accepted Pi-Rat names, and a rat must perform a legendary feat to add a new name to the list.
### Other Peoples of Yeld
* **King's People**: Human in appearance with pointed ears. The original rulers of Yeld before Dragul's usurpation.
* **Fairies**: Large, furry creatures with pointed ears, sharp teeth, and flat feet. Sturdy, strong enough to throw a bull, and loyal to Dragul.
* **Mermaids**: Daughters of the Deep. Humanoid with finned ears and tails that propel them through water. They can transform their tails into legs to walk and fight on land.
* **Squidfolk**: The Deep's first creations. Retain weird squid heads. Initially poor spies, they now live peacefully in Yeld after being replaced by the Octopus Tribe.
* **Vampires**: Created by Dragul. Possess Fairy-like strength, speed, and immortality, but must consume flesh and blood to survive. Only King's People and Mermaids can become Vampires.
* **Goblins**: Short, mossy-green beings with large ears and stubby tails. They wear containment suits because they cannot breathe Yeld's air. Gifted merchants, mechanics, and traders.
* **Animal Tribes**: The true natives of Yeld who lived there before Witches or Fairies. Hundreds of tribes serve the Deep under the waves.
* **Ghosts**: Inhabitants of the Ghost World, a gray filter over reality. Ghosts can look back into the living world, watch over friends, or haunt enemies.
---
# Final Thoughts
*Rats with Gats* is about embracing madness, celebrating small victories, and telling ridiculous stories. Get silly, don't take it too seriously, and name your techniques ridiculous things (like *"The Cheese Tickler's Gambit"* or *"Omae Wa Mou Shindeiru"*). Every Pi-Rat deserves a chance at glory.
*Want more? Get the full game "The Magical Land of Yeld" at [YeldStuff.com](http://YeldStuff.com)!*

112
SOURCEMAP.md
View File

@@ -1,112 +0,0 @@
# Codebase Source Map
This document outlines the file layout and architecture of the **PiRats** (Rats with Gats Remote Play) application.
## Directory Tree
```
pirats/
├── pyproject.toml # Python package configuration (PEP 621)
├── flake.nix # Nix configuration for development and deployment
├── RULEBOOK.md # Core Rats with Gats rules
├── OBSTACLES.md # Obstacle cards list and definitions
├── EXAMPLESCENE.md # Example gameplay scene walk-through
├── SOURCEMAP.md # This file
├── src/
│ └── pirats/
│ ├── __init__.py
│ ├── cards.py # Cards, deck shuffling, and score logic
│ ├── database.py # DB connection setup and tables creation
│ ├── models.py # SQLModel schemas (Game, Player, Obstacle, Vote)
│ ├── templates.py # Shared Jinja2 templates setup
│ ├── phase_view.py # Core templates phase-view routing engine
│ ├── crud.py # Facade hub importing all sub-CRUD modules
│ ├── crud_base.py # Base player, game, hand, deck database logic
│ ├── crud_character.py # Character setup, question delegation, techniques swapping CRUD
│ ├── crud_scene.py # Scene start, cards playing, Joker replacement CRUD
│ ├── crud_upkeep.py # Upkeep transitions, rank-up voting, deep rest hand refresh CRUD
│ ├── main.py # Main FastAPI initialization and core routes
│ ├── routes_lobby.py # Lobby status and starting character creation routes
│ ├── routes_character.py # Character basic details saving, delegation, and technique submit routes
│ ├── routes_scene.py # Role choosing, playing cards, Joker replace, objective toggles routes
│ ├── routes_upkeep.py # Voting rank-up, readying, deep upkeep hand refresh routes
│ ├── routes_admin.py # Creator admin dashboard panel routes
│ ├── static/
│ │ ├── js/
│ │ │ └── suggestions.js # Suggestions dictionary for character creation
│ │ └── css/
│ │ ├── style.css # Central stylesheet hub (imports other files)
│ │ ├── core.css # Tokens, base resets, layout, utilities, global animations
│ │ ├── components.css # Panels, cards, buttons, input fields
│ │ ├── card.css # Mini, medium, large card styles, dragging styles
│ │ ├── welcome.css # Home/welcome screen styles
│ │ ├── lobby.css # Game lobby & waiting room player chip styles
│ │ ├── character.css # Character sheet grid & tactile technique drag-and-drop slots
│ │ ├── scene-setup.css # Role selection screen button & badge styles
│ │ ├── scene-play.css # Gameplay board, obstacles, challenges, deep controls
│ │ ├── upkeep.css # Upkeep rest cards, voting roster, upkeep drag/drop
│ │ └── admin.css # Admin dashboard list row layouts
│ └── templates/ # Jinja2 HTML templates
│ ├── admin.html # Session creator admin control panel
│ ├── base.html # Main base layout structure
│ ├── between_scenes_partial.html # Upkeep voting & rank ledgers view
│ ├── character_creation_partial.html # Character sheet & techniques builder view
│ ├── crew_status_snippet.html # Lobby status polling snippet
│ ├── dashboard.html # Dashboard hub containing HTMX phase swap targets
│ ├── deep_upkeep_partial.html # Deep rest upkeep card swap view
│ ├── delegation_snippet.html # Task list/inbox items for character creation
│ ├── header_status_snippet.html # Header pills showing role/phase
│ ├── inbox_snippet.html # Inboxes for likes/hates task answers
│ ├── index.html # Welcome home screen
│ ├── join_form.html # Join game form
│ ├── lobby_partial.html # Lobby view
│ ├── lobby_players_snippet.html # Lobby active players list snippet
│ ├── scene_obstacles_snippet.html # Playboard obstacles snippet
│ ├── scene_partial.html # Playboard gameplay view
│ ├── scene_roster_snippet.html # Scene roster snippet
│ ├── scene_setup_partial.html # Scene setup role chooser view
│ ├── techniques_snippet.html # Technique assignments display snippet
│ └── voting_roster_snippet.html # Voting roster display snippet
└── tests/
└── test_game.py # pytest backend logic and game loop tests
```
---
## Component Details
### 1. Backend Python Modules (`src/pirats/`)
#### Core Configuration & Setup
- **[database.py](file:///Users/ttm/Projects/pirats/src/pirats/database.py)**: Configures the SQLite database engine, sets up the session dependency `get_session`, and executes migrations for adding new table columns dynamically.
- **[models.py](file:///Users/ttm/Projects/pirats/src/pirats/models.py)**: Defines database models using SQLModel for `Game` (phase, current scene, extra obstacles), `Player` (rank, role, objectives, cards), `Obstacle` (active scene hazards, successes, played cards), and `Vote` (rank-up nominations).
- **[cards.py](file:///Users/ttm/Projects/pirats/src/pirats/cards.py)**: Holds metadata for all 54 deck cards (suits, values, Joker representations), parses individual card codes, and loads static descriptions for Obstacles.
- **[templates.py](file:///Users/ttm/Projects/pirats/src/pirats/templates.py)**: Shared Jinja2 template initialization and path configurations to avoid circular module imports.
#### Modular Business Logic (CRUD)
- **[crud.py](file:///Users/ttm/Projects/pirats/src/pirats/crud.py)**: A facade module that imports all sub-CRUD helper functions, preserving existing API endpoints for routes and tests.
- **[crud_base.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_base.py)**: Base utility functions for accessing hands, drawing cards, reshuffling, checking captain privileges, and fetching core game and player entities.
- **[crud_character.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_character.py)**: Handles delegating and answering character questions, submitting techniques, and distributing technique swaps.
- **[crud_scene.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_scene.py)**: Scene starts checks, playing normal/Joker cards onto obstacles, and checking objective checkbox completion.
- **[crud_upkeep.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_upkeep.py)**: Handles rank votes submissions/resolution, upkeep state transitions, and Deep upkeep hand discards/refreshes.
#### Modular Router Endpoints (Routes)
- **[main.py](file:///Users/ttm/Projects/pirats/src/pirats/main.py)**: Launches the FastAPI application, mounts static assets, serves home landing, game joins, dashboard layout renders, phase polling checks, and mounts all phase APIRouters.
- **[phase_view.py](file:///Users/ttm/Projects/pirats/src/pirats/phase_view.py)**: Houses `/game/{game_id}/player/{player_id}/view` which determines the template responses to return for each phase layout.
- **[routes_lobby.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_lobby.py)**: Endpoints for lobby listings and starting game creation.
- **[routes_character.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_character.py)**: Endpoints for character sheets details saving, question delegations, revocations, and technique configurations.
- **[routes_scene.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_scene.py)**: Endpoints for role assignments, scene starts, card playing, objective changes, and scene endings.
- **[routes_upkeep.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_upkeep.py)**: Endpoints for between-scene rank votes, player readiness triggers, and deep card confirmations.
- **[routes_admin.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_admin.py)**: Endpoints for host administrator console panels.
---
### 2. Frontend Stylesheets (`src/pirats/static/css/`)
- **[style.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/style.css)**: Central hub referencing all other modular files using `@import`.
- **[core.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/core.css)**: Variable definitions, colors, font styling, animations, structural body, headers/footers, loading indicators, and alerts.
- **[components.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/components.css)**: Forms input designs, buttons variants, and glassmorphic panels.
- **[card.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/card.css)**: Custom-rendered CSS playing card widgets (mini list cards, hand cards, large face cards) and dragging animation states.
- **[welcome.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/welcome.css)** / **[lobby.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/lobby.css)**: Screen styles for the landing page and multiplayer join lobbies.
- **[character.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/character.css)** / **[scene-setup.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/scene-setup.css)**: Style configurations for the character sheet setup and scene role choose slots.
- **[scene-play.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/scene-play.css)** / **[upkeep.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/upkeep.css)**: Styles for active obstacles, card tables, and voting rank ledgers.
- **[admin.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/admin.css)**: Styles for session game hosts admin controls.