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

607 lines
19 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
/** Set once someone won the world; it stays readable. */
ended_at: string | null
winner: { id: number; name: string } | null
}
/** A world as a season: crown forts appear round 0|0, holding most of them long enough wins. */
export interface SeasonState {
/** When the crowns appear, or appeared. */
crowns_at: string
count: number
/** Crowns a player must hold to start the clock. */
needed: number
/** How long the holder must keep them. */
hold_seconds: number
crowns: { id: number; name: string; x: number; y: number; player: { id: number; name: string } | null }[]
holder: { id: number; name: string } | null
/** When the holder wins if they keep the crowns. */
ends_at: string | null
ended_at: string | null
winner: { id: number; name: string } | null
}
/** `village.show`, and the reply to every `village.*` mutation. */
export type VillageRole = 'resources' | 'military'
/**
* What fills the space gives a village its role: one kind of building taking at least
* `share` of the space both kinds take, and at least `min_space`.
*/
export interface Specialisation {
role: VillageRole | null
/** Space the standing buildings of each role take. */
space: Record<VillageRole, number>
share: number
min_space: number
/** Bonuses as shares: production (camps' output), recruit_speed, defense. */
roles: { role: VillageRole; buildings: BuildingType[]; bonuses: Partial<Record<'production' | 'recruit_speed' | 'defense', number>> }[]
}
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 }
specialisation: Specialisation
season: SeasonState
/** The player's tribe and their role in it, and tribe invites waiting. */
tribe: { tribe: (TribeRef & { role: TribeRole }) | null; invites: 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
/** Raiders from a barbarian camp: no player sent them. */
raid: boolean
/** While raiders still gather at their camp: when they march. */
marches_at: 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
/** Raiders from a barbarian camp attacked; a beaten band leaves a bounty in the village. */
raid?: boolean
bounty?: Cost | 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
}
/** Raiders whose camp was beaten down before they arrived: no battle. */
export interface ScatteredRaid {
raid: true
scattered: true
attacker: { village: VillageRef; units: null; lost: null }
defender: { village: VillageRef; units: null; lost: null }
}
export type Report =
| (ReportBase & { type: 'attack' | 'defense'; payload: BattleReport | ScatteredRaid })
| (ReportBase & { type: 'support'; payload: SupportReport })
export type TribeRole = 'leader' | 'council' | 'member'
export type Pact = 'ally' | 'nap'
/** What one player's tribe is to another's. */
export type TribeRelation = 'tribe' | 'ally' | 'nap' | 'enemy' | 'none'
export interface TribeRef {
id: number
name: string
tag: string
}
/** `tribe.show` and the reply to every `tribe.*` change. */
export interface TribePage {
tribe: {
id: number
name: string
tag: string
description: string | null
/** The player's own role and player id. */
role: TribeRole
player_id: number
members: { player: { id: number; name: string }; role: TribeRole; points: number; villages: number }[]
/** Invites sent, for the leader and the council. */
invites: { player: { id: number; name: string }; at: string }[]
/**
* holds/ending: a pact both accepted (ending: until ends_at); offered: ours waiting;
* incoming: theirs waiting for us; enemy: we declared them; hostile: they declared us.
*/
relations: { tribe: TribeRef; state: Pact | 'enemy'; status: 'holds' | 'ending' | 'offered' | 'incoming' | 'enemy' | 'hostile'; ends_at: string | null }[]
events: { type: string; payload: Record<string, any>; at: string }[]
} | null
/** Invites the player has received. */
invites: { tribe: TribeRef; members: number; at: string }[]
max_members: number
/** How long ending a pact takes. */
notice_seconds: number
}
/** A chat channel as the player names it: world, tribe, or dm:<player id>. */
export interface ChatChannel {
channel: string
/** The other player of a direct conversation. */
with: { id: number; name: string } | null
unread: number
}
export interface ChatMessage {
id: number
player: { id: number; name: string }
body: string
at: string
}
/** `chat.history`: oldest first; more when older ones exist. */
export interface ChatHistory {
channel: string
messages: ChatMessage[]
more: boolean
}
/** Push `chat:message` to everyone who reads the channel. */
export interface ChatPush {
world_id: number
channel: string
message: ChatMessage
}
/** `tribe.list`: every tribe of the world, strongest first. */
export interface TribeListRow extends TribeRef {
members: number
points: number
relation: TribeRelation
}
export type RankingKind = 'players' | 'tribes' | 'villages' | 'attack' | 'defense'
export interface RankingRow {
rank: number
/** Every kind but tribes. */
player?: { id: number; name: string; tribe: { id: number; tag: string } | null }
/** Only in the tribe ranking. */
tribe?: TribeRef
members?: number
/** Only in the village ranking. */
village?: { id: number; name: string; x: number; y: number }
/** Points, or opponents defeated (by the food the fallen ate). */
value: number
/** Only in the player ranking. */
villages?: number
own: boolean
}
/** `ranking.index`: one page; without a page asked for, the one with the own row. */
export interface RankingPage {
kind: RankingKind
page: number
pages: number
rows: RankingRow[]
own: { rank: number; page: number } | null
}
/** `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
/** The form field a refused registration points at. */
field?: 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
}