game-village-politics-frontend/app/types/game.ts

453 lines
14 KiB
TypeScript
Raw Normal View History

// Payloads exchanged with the server. Every number in here is computed server-side;
// the client only projects resources and countdowns forward from the timestamps.
export type Resource = 'wood' | 'clay' | 'iron' | 'food'
export type Resources = Record<Resource, number>
export type Cost = Record<Exclude<Resource, 'food'>, number>
export type BuildingType =
| 'headquarters'
| 'storage'
| 'farm'
| 'timber_camp'
| 'clay_pit'
| 'iron_mine'
| 'hiding_place'
| 'wall'
| 'rally_point'
| 'watchtower'
| 'barracks'
| 'stable'
| 'workshop'
| 'academy'
export type UnitType =
| 'spear'
| 'sword'
| 'archer'
| 'scout'
| 'light_cavalry'
| 'heavy_cavalry'
| 'ram'
| 'catapult'
| 'nobleman'
/** Units by type; missing types mean none. */
export type Units = Partial<Record<UnitType, number>>
export type MovementType = 'attack' | 'support' | 'return'
export type TravelMode = 'sneaky' | 'cautious' | 'normal' | 'fast' | 'forced'
/** Why the server refuses an offer. The client shows `village.blocked.<reason>`; no_space means not enough free building space. */
export type BlockedReason = 'max_per_village' | 'no_space' | 'max_level' | 'requires'
export interface AuthUser {
id: number
name: string
email: string
}
/** `POST auth/login` and `POST auth/register`. */
export interface AuthResult {
token: string
user: AuthUser
}
/** Where a new village starts: anywhere on the frontier, or in one quarter of the map. */
export type StartDirection = 'random' | 'nw' | 'ne' | 'sw' | 'se'
/** One row of `world.index`. */
export interface WorldSummary {
id: number
name: string
slug: string
speed: number
village_id: number | null
}
/** `village.show`, and the reply to every `village.*` mutation. */
export interface VillageState {
id: number
world_id: number
name: string
x: number
y: number
/** Map continent, e.g. K55 for 0|0 to 99|99. */
continent: string
/** Sum of the buildings' level points, as shown on the map. */
points: number
/** Building space: what buildings and queued new buildings take, out of the village maximum. */
space: { used: number; max: number }
/** Amounts stored at `resources_at`. */
resources: Resources
resources_at: string
/** Net change per hour. Food is farm output minus upkeep, so it can be negative. */
rates: Resources
storage_cap: number
population: Population
/** Villagers drafted as militia: they eat but don't work until `until`. */
levy: Levy
starvation: Starvation
/** Own units standing in the village. */
troops: Partial<Record<UnitType, number>>
/** One entry per building that trains units, in building order. */
military: MilitaryBuilding[]
/** Own groups leaving from or coming home to this village, and spotted groups coming here; by arrival. */
movements: Movement[]
support: {
/** Support from other villages standing here, by home village. */
here: SupportGroup[]
/** This village's troops standing in other villages, by host. */
away: SupportGroup[]
}
rally: RallyInfo
/** The player's unread reports on this world. */
unread_reports: number
/** 0..100; noblemen lower it, at 0 the village changes hands. */
loyalty: number
conquest: Conquest
/** The player's villages in this world, by id: the switcher. */
villages: { id: number; name: string; x: number; y: number; points: number }[]
/** Quest book badge: lines with a completed quest to claim, level rewards to collect. */
quests: { claimable: number; rewards: number }
builders: number
buildings: Building[]
queue: BuildOrder[]
buildable: BuildOption[]
/** Lets the client correct for its own clock being off. */
server_time: string
}
/** A village as movements and reports refer to it; player null for barbarians. */
export interface VillageRef {
id: number
name: string
x: number
y: number
player: { id: number; name: string } | null
}
/** A group under way. Groups of other players show no units, mode or send time. */
export interface Movement {
id: number
type: MovementType
/** out: an own command leaving here; home: own troops coming back here; in: coming here. */
direction: 'out' | 'in' | 'home'
mode: TravelMode | null
from: VillageRef
to: VillageRef
units: Units | null
/** Loot on a return trip. */
cargo: Cost | null
sent_at: string | null
arrives_at: string
/** Until when the command can still be called back; null when it can't. */
cancel_until: string | null
}
export interface SupportGroup {
village: VillageRef
units: Units
}
export interface RallyInfo {
/** Nothing can be sent without a rally point. */
has_rally_point: boolean
/** speed multiplies the pace; visibility is the radius in fields the group is seen in (0: only on arrival). */
modes: { mode: TravelMode; speed: number; visibility: number }[]
default_mode: TravelMode
/** Fields around the village within which incoming groups are spotted. */
detection: number
/** Seconds after sending during which a command can be called back. */
cancel_window: number
/** While set, players can't attack this player, and this player can only attack barbarians. */
protected_until: string | null
}
/** `rally.preview`: what the send form shows before sending. */
export interface MarchPlan {
x: number
y: number
/** The village on that field, or null for an empty one. */
target: VillageRef | null
mode: TravelMode
distance: number
/** Travel time; null without units or for the own field. */
seconds: number | null
}
export type ReportType = 'attack' | 'defense' | 'support'
export interface BattleSide {
village: VillageRef
/** By unit; defenders may include `militia`. null where an attacker without survivors learned nothing. */
units: Record<string, number> | null
lost: Record<string, number> | null
}
export interface BattleReport {
/** Whether the attacker won. */
won: boolean
/** Percent, between −25 and 25 by default. */
luck: number
/** Percent. */
morale: number
night: boolean
attacker: BattleSide
defender: BattleSide
wall: { before: number; after: number } | null
building: { type: BuildingType; before: number; after: number } | null
loot: Cost
capacity: number
/** Noblemen survived a won attack: loyalty before and after, and whether the village changed hands. */
loyalty?: { before: number; after: number; conquered: boolean } | null
/** Only when scouts went along. Resources and buildings only when some got through. */
scouting?: {
sent: number
lost: number
through: boolean
resources: Cost | null
/** Levels of every instance, highest first. */
buildings: Partial<Record<BuildingType, number[]>> | null
} | null
}
/** `rally.simulate`: a battle on paper with the world's rules. */
export interface SimulatedBattle {
won: boolean
attacker: { units: Record<string, number>; lost: Record<string, number> }
defender: { units: Record<string, number>; lost: Record<string, number> }
wall: { before: number; after: number } | null
building: { before: number; after: number } | null
power: { attack: number; defense: number }
}
export interface SupportReport {
from: VillageRef
to: VillageRef
units: Units
}
interface ReportBase {
id: number
happened_at: string
read: boolean
}
export type Report =
| (ReportBase & { type: 'attack' | 'defense'; payload: BattleReport })
| (ReportBase & { type: 'support'; payload: SupportReport })
/** `report.index`, `report.delete` and `report.readAll`. */
export interface ReportPage {
reports: Report[]
page: number
pages: number
unread: number
}
export interface Population {
/** Food per hour the village can feed. */
food_budget: number
/** Food per hour eaten by villagers and soldiers. */
upkeep: number
villagers: number
/** Villagers assigned to buildings. */
workers: number
soldiers: number
/** Units queued but not trained yet; they already eat instead of working. */
training: number
}
export interface Levy {
/** 0 when no levy is under way. */
militia: number
/** When the militia go back to work on their own. */
until: string | null
/** How long a new levy would last. */
seconds: number
}
/** Upkeep above income drains the food stock; once it is empty, soldiers desert after a grace time. */
export interface Starvation {
/** When the stock runs out at the current rates; null while food isn't draining. */
food_empty_at: string | null
/** Set while the stock is empty and the village eats more than it harvests. */
since: string | null
/** The next desertion wave, while starving. */
desertion_at: string | null
}
/** A barracks, stable, workshop or academy: what it trains and its own queue. */
export interface MilitaryBuilding {
building_id: number
type: BuildingType
level: number
units: RecruitOption[]
queue: RecruitOrder[]
}
export interface RecruitOption {
unit: UnitType
/** Per unit. */
cost: Cost
/** Per unit at this building, from its level and staffing. */
seconds: number
/** Food per hour one unit eats. */
upkeep: number
/** Most units that resources and villagers allowed when the snapshot was taken. */
max: number
blocked: 'requires' | null
requires: { type: BuildingType; level: number }[]
}
export interface RecruitOrder {
id: number
unit: UnitType
count: number
/** Units trained by the snapshot; the rest arrive every seconds_per_unit after starts_at. */
done: number
seconds_per_unit: number
starts_at: string
finishes_at: string
}
export interface Building {
id: number
type: BuildingType
level: number
/** Building space this instance takes, fixed per type (0 for the wall). */
space: number
priority: number
workers: { assigned: number; required: number }
/** assigned / required, 0..1. */
staffing: number
production: { resource: Resource; per_hour: number } | null
/** Next level after everything already queued; null at max level. */
upgrade: Offer | null
/** null when the building cannot go lower (core buildings at level 1); target level 0 removes it. */
demolish: { target_level: number; refund: Cost; seconds: number } | null
/** What one instance does at its level, and one level up (null at max level). */
effects: BuildingEffect[]
next_effects: BuildingEffect[] | null
}
/** One line of what a building does: production at full staffing (per hour), percentages as whole numbers. */
export interface BuildingEffect {
key: 'production' | 'capacity' | 'hides' | 'detection' | 'wall_defense' | 'wall_bonus' | 'build_speed' | 'builders' | 'space' | 'recruit_speed'
value: number
resource?: Resource
}
/** Whether it is affordable is left to the client, which compares the cost to projected resources. */
export interface Offer {
target_level: number
cost: Cost
seconds: number
blocked: BlockedReason | null
}
export interface BuildOption extends Offer {
type: BuildingType
space: number
/** Requirements no building meets yet; only advanced buildings have any. */
requires: { type: BuildingType; level: number }[]
}
export interface BuildOrder {
id: number
/** null for a new instance that does not exist yet. */
building_id: number | null
type: BuildingType
action: 'build' | 'upgrade' | 'demolish'
/** 0 means the instance is removed; levels start at 1. */
target_level: number
space: number
cost: Cost
position: number
/** Builder slot working on it, or null while it waits. */
builder: number | null
starts_at: string | null
finishes_at: string | null
}
/** Push `village:updated` after the server processed an event for this village. */
export interface VillageUpdated {
village_id: number
}
/** What a rejected `ws.send` carries. */
export interface GameError {
message: string
code?: string
}
/** A screen a quest goal points at that is not a building's row on the headquarters screen. */
export type QuestScreen = 'overview' | 'recruit' | 'rally' | 'workforce' | 'map' | 'reports'
export interface QuestGoal {
/** building: a type at a level in any village; instances: that many of a type in one village; counter: an action done that often. */
kind: 'building' | 'instances' | 'counter'
/** A building type, or a counter key such as `recruited.spear`. */
subject: string
have: number
need: number
met: boolean
/** Where to go: a building type (its headquarters row) or a screen. */
hint: BuildingType | QuestScreen
}
export interface Quest {
key: string
goals: QuestGoal[]
reward: Partial<Resources>
complete: boolean
}
export interface QuestLine {
line: 'construction' | 'army' | 'village'
done: number
total: number
/** The first unclaimed quest; null once the line is finished. */
quest: Quest | null
quests: { key: string; claimed: boolean }[]
}
/** A building level reached for the first time pays back part of its cost. */
export interface LevelReward {
id: number
type: BuildingType
level: number
reward: Partial<Resources>
/** Where it was reached; it is collected into the current village. */
village: { id: number; name: string | null }
}
/** `quest.index`. */
export interface QuestBookState {
lines: QuestLine[]
rewards: LevelReward[]
/** What the next level of each building type in this village would pay back. */
upcoming: { type: BuildingType; level: number; reward: Partial<Resources> }[]
/** Share of a level's cost paid back, 0..1. */
share: number
}
/** `quest.claim` and `quest.collect`. */
export interface QuestClaimed {
book: QuestBookState
village: VillageState
}
/** Coins and noble slots of the player. Every nobleman alive and every village beyond the first takes a slot. */
export interface Conquest {
coins: number
slots: number
used: number
/** Coins still missing for the next slot. */
next_slot_coins: number
coin_cost: Cost
/** Fields a nobleman marches at most; 0 for no limit. */
max_distance: number
}