pokemon/nuzlocke-tracker
1
1
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add Pinwheel Clause support for zone-based encounters in route groups

Browse Source 
Allows each sub-zone within a route group to have its own independent
encounter when the Pinwheel Clause rule is enabled (default on), instead
of the entire group sharing a single encounter.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Julian Tabel
2026-02-07 20:22:36 +01:00
parent 0b874a6816
commit 4fb6d43305
16 changed files with 233 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
.beans/nuzlocke-tracker-i08l--implement-pinwheel-clause-support.md Normal file
View File

@@ -0,0 +1,25 @@
---
# nuzlocke-tracker-i08l
title: Implement Pinwheel Clause support
status: completed
type: feature
priority: normal
created_at: 2026-02-07T19:18:34Z
updated_at: 2026-02-07T19:21:45Z
---
Add pinwheel_zone column to routes, pinwheelClause toggle to NuzlockeRules, zone-aware encounter locking on frontend and backend.
## Checklist
- [x] Alembic migration for pinwheel_zone column
- [x] SQLAlchemy model update
- [x] Pydantic schema updates
- [x] Route list API helper update
- [x] Encounter creation API zone-aware sibling check
- [x] Seed loader update
- [x] Seed data for Pinwheel Forest zones
- [x] NuzlockeRules per-run toggle
- [x] Frontend types (game.ts, admin.ts)
- [x] Admin route form pinwheelZone input
- [x] Encounter page zone-aware locking, counts, and filtering
- [x] getZoneEncounters helper

29
backend/src/app/alembic/versions/a1b2c3d4e5f7_add_pinwheel_clause_support.py Normal file
View File

@@ -0,0 +1,29 @@
"""add pinwheel clause support
Revision ID: a1b2c3d4e5f7
Revises: f6a7b8c9d0e1
Create Date: 2026-02-07 12:00:00.000000
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = 'a1b2c3d4e5f7'
down_revision: Union[str, Sequence[str], None] = 'f6a7b8c9d0e1'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.add_column(
'routes',
sa.Column('pinwheel_zone', sa.SmallInteger(), nullable=True),
)
def downgrade() -> None:
op.drop_column('routes', 'pinwheel_zone')

25
backend/src/app/api/encounters.py
View File

@@ -50,15 +50,30 @@ async def create_encounter(
detail="Cannot create encounter on a parent route. Use a child route instead.",
)
# If this route has a parent, check if any sibling already has an encounter
# If this route has a parent, check if sibling already has an encounter
if route.parent_route_id is not None:
# Get all sibling route IDs (routes with same parent, including this one)
# Get all sibling routes (routes with same parent, including this one)
siblings_result = await session.execute(
select(Route.id).where(Route.parent_route_id == route.parent_route_id)
select(Route).where(Route.parent_route_id == route.parent_route_id)
)
sibling_ids = [r for r in siblings_result.scalars().all()]
siblings = siblings_result.scalars().all()
# Check if any sibling already has an encounter in this run
# Determine which siblings to check based on pinwheel clause
pinwheel_on = run.rules.get("pinwheelClause", True) if run.rules else True
any_has_zone = any(s.pinwheel_zone is not None for s in siblings)
if pinwheel_on and any_has_zone:
# Zone-aware: only check siblings in the same zone (null treated as 0)
my_zone = route.pinwheel_zone if route.pinwheel_zone is not None else 0
sibling_ids = [
s.id for s in siblings
if (s.pinwheel_zone if s.pinwheel_zone is not None else 0) == my_zone
]
else:
# No pinwheel clause or no zones defined: all siblings share
sibling_ids = [s.id for s in siblings]
# Check if any relevant sibling already has an encounter in this run
existing_encounter = await session.execute(
select(Encounter)
.where(

1
backend/src/app/api/games.py
View File

@@ -80,6 +80,7 @@ async def list_game_routes(
"game_id": route.game_id,
"order": route.order,
"parent_route_id": route.parent_route_id,
"pinwheel_zone": route.pinwheel_zone,
"encounter_methods": methods,
}

1
backend/src/app/models/route.py
View File

@@ -17,6 +17,7 @@ class Route(Base):
parent_route_id: Mapped[int | None] = mapped_column(
ForeignKey("routes.id", ondelete="CASCADE"), index=True, default=None
)
pinwheel_zone: Mapped[int | None] = mapped_column(SmallInteger, default=None)
game: Mapped["Game"] = relationship(back_populates="routes")
route_encounters: Mapped[list["RouteEncounter"]] = relationship(

3
backend/src/app/schemas/game.py
View File

@@ -7,6 +7,7 @@ class RouteResponse(CamelModel):
game_id: int
order: int
parent_route_id: int | None = None
pinwheel_zone: int | None = None
encounter_methods: list[str] = []
@@ -56,12 +57,14 @@ class RouteCreate(CamelModel):
name: str
order: int
parent_route_id: int | None = None
pinwheel_zone: int | None = None
class RouteUpdate(CamelModel):
name: str | None = None
order: int | None = None
parent_route_id: int | None = None
pinwheel_zone: int | None = None
class RouteReorderItem(CamelModel):

2
backend/src/app/seeds/data/black-2.json
View File

@@ -1333,6 +1333,7 @@
{
"name": "Pinwheel Forest (Outside)",
"order": 23,
"pinwheel_zone": 1,
"encounters": [
{
"pokeapi_id": 533,
@@ -1379,6 +1380,7 @@
{
"name": "Pinwheel Forest (Inside)",
"order": 24,
"pinwheel_zone": 2,
"encounters": [
{
"pokeapi_id": 550,

2
backend/src/app/seeds/data/black.json
View File

@@ -1321,6 +1321,7 @@
{
"name": "Pinwheel Forest (Outside)",
"order": 25,
"pinwheel_zone": 1,
"encounters": [
{
"pokeapi_id": 535,
@@ -1359,6 +1360,7 @@
{
"name": "Pinwheel Forest (Inside)",
"order": 26,
"pinwheel_zone": 2,
"encounters": [
{
"pokeapi_id": 550,

2
backend/src/app/seeds/data/white-2.json
View File

@@ -1333,6 +1333,7 @@
{
"name": "Pinwheel Forest (Outside)",
"order": 23,
"pinwheel_zone": 1,
"encounters": [
{
"pokeapi_id": 533,
@@ -1379,6 +1380,7 @@
{
"name": "Pinwheel Forest (Inside)",
"order": 24,
"pinwheel_zone": 2,
"encounters": [
{
"pokeapi_id": 10016,

2
backend/src/app/seeds/data/white.json
View File

@@ -1321,6 +1321,7 @@
{
"name": "Pinwheel Forest (Outside)",
"order": 25,
"pinwheel_zone": 1,
"encounters": [
{
"pokeapi_id": 535,
@@ -1359,6 +1360,7 @@
{
"name": "Pinwheel Forest (Inside)",
"order": 26,
"pinwheel_zone": 2,
"encounters": [
{
"pokeapi_id": 10016,

7
backend/src/app/seeds/loader.py
View File

@@ -109,9 +109,14 @@ async def upsert_routes(
game_id=game_id,
order=child["order"],
parent_route_id=parent_id,
pinwheel_zone=child.get("pinwheel_zone"),
).on_conflict_do_update(
constraint="uq_routes_game_name",
set_={"order": child["order"], "parent_route_id": parent_id},
set_={
"order": child["order"],
"parent_route_id": parent_id,
"pinwheel_zone": child.get("pinwheel_zone"),
},
)
await session.execute(stmt)

23
frontend/src/components/admin/RouteFormModal.tsx
View File

@@ -13,10 +13,17 @@ interface RouteFormModalProps {
export function RouteFormModal({ route, nextOrder, onSubmit, onClose, isSubmitting }: RouteFormModalProps) {
const [name, setName] = useState(route?.name ?? '')
const [order, setOrder] = useState(String(route?.order ?? nextOrder ?? 0))
const [pinwheelZone, setPinwheelZone] = useState(
route?.pinwheelZone != null ? String(route.pinwheelZone) : ''
)
const handleSubmit = (e: FormEvent) => {
e.preventDefault()
onSubmit({ name, order: Number(order) })
onSubmit({
name,
order: Number(order),
pinwheelZone: pinwheelZone !== '' ? Number(pinwheelZone) : null,
})
}
return (
@@ -47,6 +54,20 @@ export function RouteFormModal({ route, nextOrder, onSubmit, onClose, isSubmitti
className="w-full px-3 py-2 border rounded-md dark:bg-gray-700 dark:border-gray-600"
/>
</div>
<div>
<label className="block text-sm font-medium mb-1">Pinwheel Zone</label>
<input
type="number"
min={0}
value={pinwheelZone}
onChange={(e) => setPinwheelZone(e.target.value)}
placeholder="None"
className="w-full px-3 py-2 border rounded-md dark:bg-gray-700 dark:border-gray-600"
/>
<p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
Routes in the same zone share an encounter when the Pinwheel Clause is active
</p>
</div>
</FormModal>
)
}

121
frontend/src/pages/RunEncounters.tsx
View File

@@ -103,6 +103,40 @@ function getGroupEncounter(
return null
}
/** Whether any child in this group has a pinwheelZone set. */
function groupHasZones(group: RouteWithChildren): boolean {
return group.children.some((c) => c.pinwheelZone != null)
}
/** Get the effective zone for a route (null treated as 0). */
function effectiveZone(route: Route): number {
return route.pinwheelZone ?? 0
}
/**
* Get encounters grouped by zone within a route group.
* Returns a Map from zone number to the encounter in that zone.
*/
function getZoneEncounters(
group: RouteWithChildren,
encounterByRoute: Map<number, EncounterDetail>,
): Map<number, EncounterDetail> {
const zoneMap = new Map<number, EncounterDetail>()
for (const child of group.children) {
const enc = encounterByRoute.get(child.id)
if (enc) {
zoneMap.set(effectiveZone(child), enc)
}
}
return zoneMap
}
/** Count distinct zones in a group. */
function countDistinctZones(group: RouteWithChildren): number {
const zones = new Set(group.children.map(effectiveZone))
return zones.size
}
interface RouteGroupProps {
group: RouteWithChildren
encounterByRoute: Map<number, EncounterDetail>
@@ -110,6 +144,7 @@ interface RouteGroupProps {
onToggleExpand: () => void
onRouteClick: (route: Route) => void
filter: 'all' | RouteStatus
pinwheelClause: boolean
}
function RouteGroup({
@@ -119,14 +154,37 @@ function RouteGroup({
onToggleExpand,
onRouteClick,
filter,
pinwheelClause,
}: RouteGroupProps) {
const groupEncounter = getGroupEncounter(group, encounterByRoute)
const groupStatus = groupEncounter ? groupEncounter.status : 'none'
const usePinwheel = pinwheelClause && groupHasZones(group)
const zoneEncounters = usePinwheel
? getZoneEncounters(group, encounterByRoute)
: null
// For pinwheel groups, determine status from all zone statuses
let groupStatus: RouteStatus
if (usePinwheel && zoneEncounters && zoneEncounters.size > 0) {
// Use the first encounter's status as representative for the header
groupStatus = groupEncounter ? groupEncounter.status : 'none'
} else {
groupStatus = groupEncounter ? groupEncounter.status : 'none'
}
const si = statusIndicator[groupStatus]
// For groups, check if it matches the filter
if (filter !== 'all' && groupStatus !== filter) {
return null
if (filter !== 'all') {
if (usePinwheel) {
// Show group if any zone matches the filter
const anyChildMatches = group.children.some((child) => {
const enc = encounterByRoute.get(child.id)
return getRouteStatus(enc) === filter
})
// Also check children without encounters (for 'none' filter)
if (!anyChildMatches) return null
} else if (groupStatus !== filter) {
return null
}
}
const hasGroupEncounter = groupEncounter !== null
@@ -192,7 +250,16 @@ function RouteGroup({
const childEncounter = encounterByRoute.get(child.id)
const childStatus = getRouteStatus(childEncounter)
const childSi = statusIndicator[childStatus]
const isDisabled = hasGroupEncounter && !childEncounter
let isDisabled: boolean
if (usePinwheel && zoneEncounters) {
// Zone-aware: only lock if this child's zone already has an encounter
const myZone = effectiveZone(child)
isDisabled = zoneEncounters.has(myZone) && !childEncounter
} else {
// Classic: whole group shares one encounter
isDisabled = hasGroupEncounter && !childEncounter
}
return (
<button
@@ -334,17 +401,32 @@ export function RunEncounters() {
)
}
// Count completed locations (groups count as 1, standalone routes count as 1)
const completedCount = organizedRoutes.filter((r) => {
if (r.children.length > 0) {
// It's a group - check if any child has an encounter
return getGroupEncounter(r, encounterByRoute) !== null
}
// Standalone route
return encounterByRoute.has(r.id)
}).length
const pinwheelClause = run.rules?.pinwheelClause ?? true
const totalLocations = organizedRoutes.length
// Count completed locations (zone-aware when pinwheel clause is on)
let completedCount = 0
let totalLocations = 0
for (const r of organizedRoutes) {
if (r.children.length > 0) {
const usePinwheel = pinwheelClause && groupHasZones(r)
if (usePinwheel) {
const distinctZones = countDistinctZones(r)
const zoneEncs = getZoneEncounters(r, encounterByRoute)
totalLocations += distinctZones
completedCount += zoneEncs.size
} else {
totalLocations += 1
if (getGroupEncounter(r, encounterByRoute) !== null) {
completedCount += 1
}
}
} else {
totalLocations += 1
if (encounterByRoute.has(r.id)) {
completedCount += 1
}
}
}
const isActive = run.status === 'active'
const alive = run.encounters.filter(
@@ -413,7 +495,15 @@ export function RunEncounters() {
if (filter === 'all') return true
if (r.children.length > 0) {
// It's a group
const usePinwheel = pinwheelClause && groupHasZones(r)
if (usePinwheel) {
// Show group if any child/zone matches the filter
return r.children.some((child) => {
const enc = encounterByRoute.get(child.id)
return getRouteStatus(enc) === filter
})
}
// Classic: single status for whole group
const groupEnc = getGroupEncounter(r, encounterByRoute)
return getRouteStatus(groupEnc ?? undefined) === filter
}
@@ -665,6 +755,7 @@ export function RunEncounters() {
onToggleExpand={() => toggleGroup(route.id)}
onRouteClick={handleRouteClick}
filter={filter}
pinwheelClause={pinwheelClause}
/>
)
}

2
frontend/src/types/admin.ts
View File

@@ -19,11 +19,13 @@ export interface UpdateGameInput {
export interface CreateRouteInput {
name: string
order: number
pinwheelZone?: number | null
}
export interface UpdateRouteInput {
name?: string
order?: number
pinwheelZone?: number | null
}
export interface RouteReorderItem {

1
frontend/src/types/game.ts
View File

@@ -15,6 +15,7 @@ export interface Route {
gameId: number
order: number
parentRouteId: number | null
pinwheelZone: number | null
encounterMethods: string[]
}

9
frontend/src/types/rules.ts
View File

@@ -5,6 +5,7 @@ export interface NuzlockeRules {
nicknameRequired: boolean
duplicatesClause: boolean
shinyClause: boolean
pinwheelClause: boolean
// Difficulty modifiers
hardcoreMode: boolean
@@ -19,6 +20,7 @@ export const DEFAULT_RULES: NuzlockeRules = {
nicknameRequired: true,
duplicatesClause: true,
shinyClause: true,
pinwheelClause: true,
// Difficulty modifiers - off by default
hardcoreMode: false,
@@ -70,6 +72,13 @@ export const RULE_DEFINITIONS: RuleDefinition[] = [
'Shiny Pokémon may always be caught, regardless of whether they are your first encounter.',
category: 'core',
},
{
key: 'pinwheelClause',
name: 'Pinwheel Clause',
description:
'Sub-zones within a location group each get their own encounter instead of sharing one.',
category: 'core',
},
// Difficulty modifiers
{