Events

Active game events and their scoreboards behind client.events.

events.service

The running events, as the state keeps them, and their scoreboards.

Classes:

Name	Description
EventsService	The server's active events, your event leagues and the events' scoreboards.

EventsService

EventsService(client: 'EmpireClient')

Bases: BaseService

The server's active events, your event leagues and the events' scoreboards.

Reached as client.events.

Methods:

Name	Description
get_active_event_ids	The running events' ids, in the order they started; empty before login.
refresh	Ask the server for the running events and return them once its sei is applied.
get_league_id	Get the league your score is in for an event, the LID of its sei entry.
get_running_score_events	The running events that have a scoreboard, in the order they started.
scoreboard	The boards an event's dialogs open.
get_scores	Get a page of a running event's scoreboard, the board its dialog opens.
get_own_points	Ask the server for your rank and points in a running event.
get_active_events	The running events with their in-game titles, in the order they started.

get_active_event_ids

get_active_event_ids() -> list[int]

The running events' ids, in the order they started; empty before login.

refresh

refresh(timeout: float = 5.0) -> dict[int, SpecialEvent]

Ask the server for the running events and return them once its sei is applied.

The server's answer updates the events as any sei does; events it does not name keep running until a see or their time ends them. It asks for the sei events only: the trigger events (the kingdoms league, the global effects) come with the login data's tei and the tei pushes.

Raises:

Type	Description
CommandError	The server refused the request
EmpireTimeoutError	No sei within timeout

Client: C2SSpecialEventInfoVO (bundle line 37406)

get_league_id

get_league_id(event_id: int, part: str | None = None) -> int

Get the league your score is in for an event, the LID of its sei entry.

Pass it as league_type_id to client.ranking.get_ranking_list, get_own_ranking_page and get_ranking_window, as the client's leaderboard dialogs do. get_scores reads it for you.

Parameters:

Name	Type	Description	Default
event_id	int	The event (EID)	required
part	str | None	One part of the entry instead, for the invasion boards: SP (players), A (alliances), FB or FR (Berimond invasion's blue and red players)	None

Returns:

Type	Description
int	The league, 1 (the client's default) for a running event or part without one

Raises:

Type	Description
EventNotRunningError	The event is not running

Client: AScoreEventVO.parseBasicsFromParamObject (bundle line 14967), defaults at bundle line 14965, read by GlobalLeaderBoardLeagueComponent (bundle line 100470)

get_running_score_events

get_running_score_events() -> list[Event]

The running events that have a scoreboard, in the order they started.

scoreboard

scoreboard(event: Event) -> Scoreboard

The boards an event's dialogs open.

Raises:

Type	Description
ValueError	The event has no scoreboard; the message names the events that have one

get_scores

get_scores(event: Event, *, alliance: bool = False, list_type: RankingType | None = None, rank: int | None = None, name: str | None = None, league_id: int | None = None, page_size: int = 10, timeout: float = 5.0) -> EventScores

Get a page of a running event's scoreboard, the board its dialog opens.

With neither rank nor name the page holds your own score, where the client's dialogs open; rank=1 is the top of the board.

Parameters:

Name	Type	Description	Default
event	Event	The event, e.g. Event.FACTION (Berimond); EVENT_SCOREBOARDS lists those with a board	required
alliance	bool	Read the alliance board instead of the player board	False
list_type	RankingType | None	One of the event's boards by its list, for Berimond invasion's player boards (FACTION_INVASION_PLAYER_BLUE or FACTION_INVASION_PLAYER_RED)	None
rank	int | None	The page from this rank (leaderboards), or the page around it (hgh boards)	None
name	str | None	The page around this name: hgh's search, or for a leaderboard its search (slse) and the page of the first hit	None
league_id	int | None	Another of the event's leagues, whose top is then shown; by default your own as the sei packets gave it, 1 when they gave none (the client's default), and none for the donation board. While Berimond is locked to you (no UL in its sei entry) it opens on the top of league 1, as the client does	None
page_size	int	Rows per page on the leaderboards (M); an hgh page is as long as the server makes it (8 rows, seen live)	10
timeout	float	Timeout in seconds, per request	5.0

Returns:

Type	Description
EventScores	The page; no rows when a leaderboard search finds no one (the client then
EventScores	shows your own page instead)

Raises:

Type	Description
EventNotRunningError	The event is not running
ReplyMismatchError	The hgh reply is for a list that is not the event's
ValueError	The event has no scoreboard or no such board; rank is below 1; alliance was given with a player board; Berimond invasion's player board was asked for without list_type; rank and name were both given, or name is empty
CommandError	The server refused the request
EmpireTimeoutError	No answer; seen live for your own page of a player board with no event running

Client: the hgh boards, CastleGenericHighscoreDialog (bundle line 30799), CastleGenericAllianceHighscoreDialog (bundle line 38103) and CastleGenericRankingComponent (bundle line 29585), send "-1" (or your rank) for your own page, "1" for the top and a name to search, with the board's league, and "1" in a league that is not yours (scrollLeagueUp, bundle line 30846); FactionRankingComponent.generateProperties (bundle line 95410) opens a locked Berimond (FactionEventVO.isLocked, bundle line 7379) on league 1 at "1"; the leaderboards open on LeaderBoardDataProvider.getCurrentPlayerPage (bundle line 75941) from GlobalLeaderBoardComponent.onShow (bundle line 34990)

get_own_points

get_own_points(event: Event | int, timeout: float = 5.0) -> GetEventPointsResponse

Ask the server for your rank and points in a running event.

Works for the events in POINT_EVENTS, those without a scoreboard too (the gacha events, the lucky wheel, the alliance tournament). The reply is applied to the event's state before this returns, so client.state.get_event(event) then holds them read the event's way (own_rank, own_points, parts, ...).

Parameters:

Name	Type	Description	Default
event	Event | int	The event, e.g. Event.POINT_EVENT	required
timeout	float	Timeout in seconds	5.0

Returns:

Type	Description
GetEventPointsResponse	The reply: its lists hold one value per score the event keeps, in the order
GetEventPointsResponse	GetEventPointsResponse gives

Raises:

Type	Description
EventHasNoPointsError	The event keeps no rank and points (a shop or sale event); nothing is sent, as the server answers none (seen live)
EventNotRunningError	The event is not running
CommandError	The server refused the request
EmpireTimeoutError	No answer within timeout, or only one for another event

Client: C2SPointEventGetPointsVO (bundle line 8697), sent by the event dialogs only for a running event (e.g. CastleFactionInvasionEventDialog.showLoaded, bundle line 91529; CastleAllianceSamuraiInvasionDialogAllianceSublayer.show, bundle line 98938); PEPCommand.exec (bundle line 128209)

get_active_events

get_active_events(lang: str = 'en', force_refresh: bool = False) -> list[GameEvent]

The running events with their in-game titles, in the order they started.

The titles come from the game's language CDN (see get_event_titles); without one, an event is named by its Event member, or its id when the library does not know it. An empty list means no event is running: a CDN outage only costs the titles.

Parameters:

Name	Type	Description	Default
lang	str	Language code for the titles (default: "en")	'en'
force_refresh	bool	Fetch the titles again even when the cached ones are fresh	False

Example

for event in client.events.get_active_events():
    print(event.display_name, round(event.details.remaining_seconds()))

events.models

The running events as the state keeps them, the events that have a scoreboard, and a page of one as client.events.get_scores returns it.

Classes:

Name	Description
Scoreboard	The boards an event's dialogs open, and the dialog the lists come from.
EventScore	One row of an event's scoreboard: a player, or an alliance on an alliance board.
EventScores	A page of an event's scoreboard.
ReadOnlyDict	A dict that refuses changes, so an event model handed out never changes.
EventPart	One score of an event with several: an invasion's player or alliance score, or a raid's own score.
SpecialEvent	A running event, as its sei (or tei) entries left it.
ScoredEvent	An event with a score of your own.
PointEvent	The nobility contest, and the base of LuckyWheelEvent: the lucky wheels keep the same score
LeagueScoredEvent	A score event whose rewards come from a reward set.
BeggingKnightsEvent	The marauders' contest.
LongTermPointEvent	The grand nobility prize.
GachaEvent	A gacha event.
InvasionEvent	An invasion: its player and alliance scores are its parts.
SamuraiInvasionEvent	The samurai invasion. Client: SamuraiInvasionEventVO.parseData (bundle line 55680)
FactionInvasionEvent	The Berimond invasion: FB and FR are the blue and red players' scores, A the alliance's.
AlienInvasionEvent	The war of the realms (71) and the Bloodcrow invasion (103); a part is rebuilt only from an entry that has it.
NomadInvasionEvent	The nomad invasion: SP and A (rebuilt from an entry that has them) and, while the khan
BerimondEvent	Battle for Berimond. Your rank and points come only from pep pushes and start over with each entry.
RaidBossEvent	The alliance raid boss: score is your own score, the alliance's is in alliance_points.
TempServerEvent	A temporary server.
DonationEvent	Imperial patronage.
KingdomsLeagueEvent	The kingdoms league, a trigger event. It runs while it has more than a day left; on its last
GlobalEffectTimer	One global effect of a global effect event.
GlobalEffectEvent	The global effects running, a trigger event that ends with the last of them.
GlobalEffectBoost	A global effect a boost event can strengthen.
GlobalEffectBuffEvent	The global effect boost, a trigger event that ends when the global effect event running as it
AllianceTournamentEvent	The alliance tournament: your own score, and your alliance's in parts["A"], which the pep pushes update.
AllianceMobilizationEvent	The alliance mobilisation: parts["SP"] is your score and parts["A"] your alliance's,
LuckyWheelEvent	The lucky wheel (15) and the sale days lucky wheel (89): a point event score and the wheel's state.
ArtifactEvent	An artifact event: the parts of the artifact you have found.
SeasonEvent	A season event: the Thornking (2), the Sea Queen (4) or the Underworld (64).
FameBoosterEvent	The fame booster. Client: FameboosterEventVO.parseParamObject (bundle line 116103)
AllianceBonusEvent	An alliance payment bonus: the prime alliance bonus (45) or the alliance payment bonus (55).
DiscountSaleEvent	A prime sale with one discount: the relic enchanter sale (88) or the season pass sale (599).
SkipForFreeEvent	Free skips. Client: SkipForFreeEventVO.parseParamObject (bundle line 118150)
GiftEvent	The Goodgame gift. Client: GGSGiftEventVO.parseParamObject (bundle line 116370)
FortuneTellerEvent	The fortune teller. Client: FortuneTellerEventVO.parseParamObject (bundle line 116134)
TournamentRank	One place of the tournament of fame's ranking: [rank, fame points, owner record].
TournamentEvent	The tournament of fame: the ranking, your place and the fame you have earned.
CampaignEvent	A time-limited campaign: its quests, in the order they open, and its end reward.
CampaignQuestEvent	The time-limited campaign's quest event; its end is the end of the campaign quests it names.
SpecialEventInfoRequest	Ask for the running events; the server answers with a sei.
GetEventPointsRequest	Ask for your rank and points in a running event; the server answers with a pep.
GetEventPointsResponse	Your rank and points in an event, pushed as you score and sent in answer to a GetEventPointsRequest.
GameEvent	A running event with its in-game title.

Functions:

Name	Description
event_class	The model an event's entries are read into.

Attributes:

Name	Type	Description
EVENT_SCOREBOARDS	dict[Event, Scoreboard]	The events whose dialogs open a scoreboard.
EVENT_CLASSES	dict[Event, type[SpecialEvent]]	The model each event's entries are read into; any other event is a plain SpecialEvent.
POINT_EVENTS	frozenset[Event]	The events that keep your rank and points, the ones a pep is answered for.

EVENT_SCOREBOARDS module-attribute

EVENT_SCOREBOARDS: dict[Event, Scoreboard] = {Event.FACTION: Scoreboard(player_lists=(RankingType.FACTION_TOURNAMENT,), source='FactionRankingComponent.generateProperties (bundle line 95410)'), Event.POINT_EVENT: Scoreboard(player_lists=(RankingType.POINT_EVENT,), source='CastlePointEventDialog (bundle line 117423)'), Event.BEGGING_KNIGHTS: Scoreboard(player_lists=(RankingType.BEGGING_KNIGHTS,), source='CastleBeggingKnightsDialog (bundle line 114835)'), Event.ALLIANCE_ALIEN_INVASION: Scoreboard(player_lists=(RankingType.ALLIANCE_ALIEN_INVASION_PLAYER,), alliance_list=RankingType.ALLIANCE_ALIEN_INVASION_ALLIANCE, source='CastleAllianceAlienInvasionEventDialogProperties (bundle lines 114205-114207)'), Event.ALLIANCE_NOMAD_INVASION: Scoreboard(player_lists=(), alliance_list=RankingType.ALLIANCE_NOMADINVASION_ALLIANCE, source='CastleAllianceNomadInvasionPointsEventSublayer (bundle line 98542); no player board'), Event.SAMURAI_INVASION: Scoreboard(player_lists=(), alliance_list=RankingType.SAMURAI_ALLIANCE, source='CastleAllianceSamuraiInvasionDialogAllianceSublayer (bundle line 98953); no player board'), Event.LONG_TERM_POINT_EVENT: Scoreboard(player_lists=(RankingType.LONG_TERM_POINT_EVENT,), is_leaderboard=True, source='LongtermPointEventGlobalLeaderBoardDialog (bundle line 100413)'), Event.FACTION_INVASION: Scoreboard(player_lists=(RankingType.FACTION_INVASION_PLAYER_BLUE, RankingType.FACTION_INVASION_PLAYER_RED), alliance_list=RankingType.FACTION_INVASION_ALLIANCE, source='CastleFactionInvasionEventHighscoreDialog (bundle lines 53151-53155)'), Event.RED_ALLIANCE_ALIEN_INVASION: Scoreboard(player_lists=(RankingType.ALLIANCE_RED_ALIEN_INVASION_PLAYER,), alliance_list=RankingType.ALLIANCE_RED_ALIEN_INVASION_ALLIANCE, source='CastleRedAllianceAlienInvasionEventDialogProperties (bundle lines 117712-117714)'), Event.DONATION_EVENT: Scoreboard(player_lists=(RankingType.DONATION_EVENT,), is_leaderboard=True, source='DonationEventDialogRanking (bundle line 115746)')}

The events whose dialogs open a scoreboard.

Client: EventConst.EVENTTYPE_* (dll line 19291) for the ids; each board's dialog in its source

EVENT_CLASSES module-attribute

EVENT_CLASSES: dict[Event, type[SpecialEvent]] = {Event.FACTION: BerimondEvent, Event.POINT_EVENT: PointEvent, Event.BEGGING_KNIGHTS: BeggingKnightsEvent, Event.LONG_TERM_POINT_EVENT: LongTermPointEvent, Event.ALLIANCE_ALIEN_INVASION: AlienInvasionEvent, Event.RED_ALLIANCE_ALIEN_INVASION: AlienInvasionEvent, Event.ALLIANCE_NOMAD_INVASION: NomadInvasionEvent, Event.SAMURAI_INVASION: SamuraiInvasionEvent, Event.FACTION_INVASION: FactionInvasionEvent, Event.ALLIANCE_RAIDBOSS_EVENT: RaidBossEvent, Event.TEMP_SERVER: TempServerEvent, Event.DONATION_EVENT: DonationEvent, Event.GACHA_DECO2X2: GachaEvent, Event.CHRISTMAS_GACHA: GachaEvent, Event.EASTER_GACHA: GachaEvent, Event.SUMMER_GACHA: GachaEvent, Event.ANNIVERSARY_GACHA: GachaEvent, Event.HALLOWEEN_GACHA: GachaEvent, Event.BLACK_FRIDAY_GACHA: GachaEvent, Event.CARNIVAL_GACHA: GachaEvent, Event.SEASON_LEAGUE: KingdomsLeagueEvent, Event.GLOBAL_EFFECT: GlobalEffectEvent, Event.GLOBAL_EFFECT_BUFF: GlobalEffectBuffEvent, Event.ALLI_TOURNAMENT: AllianceTournamentEvent, Event.ALLIANCE_MOBILIZATION_EVENT: AllianceMobilizationEvent, Event.LUCKY_WHEEL: LuckyWheelEvent, Event.SALE_DAYS_LUCKY_WHEEL: LuckyWheelEvent, **dict.fromkeys((Event.ARTIFACT_19, Event.ARTIFACT_23, Event.ARTIFACT_29, Event.ARTIFACT_30, Event.ARTIFACT_67), ArtifactEvent), **dict.fromkeys((Event.THORNKING, Event.SEAQUEEN, Event.UNDERWORLD), SeasonEvent), Event.FAMEBOOSTER: FameBoosterEvent, Event.PRIME_ALLI_BONUS: AllianceBonusEvent, Event.ALLI_PAYMENT_BONUS: AllianceBonusEvent, Event.RELIC_ENCHANTER_PRIME_SALE: DiscountSaleEvent, Event.SEASON_PASS_PRIME_SALE: DiscountSaleEvent, Event.SKIP_FOR_FREE: SkipForFreeEvent, Event.GGS_GIFT: GiftEvent, Event.FORTUNE_TELLER: FortuneTellerEvent, Event.TOURNAMENT: TournamentEvent, Event.TIME_LIMITED_CAMPAIGN_EVENT: CampaignEvent, Event.TIME_LIMITED_CAMPAIGN_QUEST_EVENT: CampaignQuestEvent}

The model each event's entries are read into; any other event is a plain SpecialEvent.

Client: CastleSpecialEventFactory.createByEventType (bundle line 61602) picks the class from the event's eventType

POINT_EVENTS module-attribute

POINT_EVENTS: frozenset[Event] = frozenset({Event.FACTION, Event.LUCKY_WHEEL, Event.ALLI_TOURNAMENT, Event.POINT_EVENT, Event.BEGGING_KNIGHTS, Event.ALLIANCE_ALIEN_INVASION, Event.ALLIANCE_NOMAD_INVASION, Event.SAMURAI_INVASION, Event.LONG_TERM_POINT_EVENT, Event.FACTION_INVASION, Event.SALE_DAYS_LUCKY_WHEEL, Event.RED_ALLIANCE_ALIEN_INVASION, Event.GACHA_DECO2X2, Event.CHRISTMAS_GACHA, Event.EASTER_GACHA, Event.ALLIANCE_MOBILIZATION_EVENT, Event.SUMMER_GACHA, Event.ANNIVERSARY_GACHA, Event.HALLOWEEN_GACHA, Event.ALLIANCE_RAIDBOSS_EVENT, Event.BLACK_FRIDAY_GACHA, Event.CARNIVAL_GACHA})

The events that keep your rank and points, the ones a pep is answered for.

Client: CastleSpecialEventFactory.createByEventType (bundle line 61602) builds each event as its eventType + EventVO; these are the classes with a setRankAndPoints, which PEPCommand.exec (bundle line 128213) calls: AScoreEventVO (bundle line 15044) and its subclasses (the nobility contest, marauders, long-term points, alliance tournament (bundle line 114412), the invasions (bundle lines 55701, 58926, 114310, 116056), the alliance mobilisation (bundle line 5101) and the gacha events, AGachaEventVO, bundle line 15372), FactionEventVO (bundle line 7461), AllianceRaidbossEventEventVO (bundle line 9117) and LuckyWheelEventVO (bundle line 59687) with SaleDaysLuckyWheelEventVO (bundle line 117863). Every other event class is an ASpecialEventVO (bundle line 2953) without one.

Scoreboard pydantic-model

Bases: EmpireModel

The boards an event's dialogs open, and the dialog the lists come from.

Fields:

• player_lists (tuple[RankingType, ...])
• alliance_list (RankingType | None)
• is_leaderboard (bool)
• source (str)

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True)

player_lists pydantic-field

player_lists: tuple[RankingType, ...]

The player boards; Berimond invasion has one per faction, blue first

alliance_list pydantic-field

alliance_list: RankingType | None = None

The alliance board, or None without one

is_leaderboard pydantic-field

is_leaderboard: bool = False

Whether the boards are read with llsp, llsw and slse rather than hgh

source pydantic-field

source: str

Where the client opens the boards

lists property

lists: tuple[RankingType, ...]

Every board, the player boards first.

EventScore pydantic-model

Bases: EmpireModel

One row of an event's scoreboard: a player, or an alliance on an alliance board.

Client: CastleGenericHighscoreDialog.onGetHighscoreData (bundle line 30827) and CastleSingleplayerRankingItem.update (bundle line 91695) read a player row as [rank, points, owner] with WorldMapOwnerInfoVO.fillFromParamObject (bundle line 10794); CastleGenericAllianceHighscoreDialog.onGetHighscoreData (bundle line 38127) and CastleAllianceRankingItem.update (bundle line 91645) read an alliance row as [rank, points, [alliance_id, name, member_count, fame]] with AllianceHighscoreInfoVO.fillFromParamObject (bundle line 27680); a leaderboard row is a LeaderboardScore

Fields:

• rank (int)
• points (int | float)
• name (str)
• player_id (int | None)
• alliance_id (int | None)
• alliance_name (str)
• level (int | None)
• member_count (int | None)
• instance_id (int | None)

rank pydantic-field

rank: int

Rank on the board

points pydantic-field

points: int | float

The event's points

name pydantic-field

name: str = ''

The player's name, or the alliance's on an alliance board

player_id pydantic-field

player_id: int | None = None

The player's id; None on alliance and leaderboard rows

alliance_id pydantic-field

alliance_id: int | None = None

The alliance's id, 0 for a player without one; None on leaderboard rows

alliance_name pydantic-field

alliance_name: str = ''

The alliance's name, empty for a player without one

level pydantic-field

level: int | None = None

The player's level; None on alliance and leaderboard rows

member_count pydantic-field

member_count: int | None = None

The alliance's member count, on alliance rows

instance_id pydantic-field

instance_id: int | None = None

The game server the player is on, on leaderboard rows

from_highscore_row classmethod

from_highscore_row(row: HighscoreRow) -> EventScore

A hgh row: a player's, or an alliance's on an alliance board.

from_leaderboard classmethod

from_leaderboard(score: LeaderboardScore) -> EventScore

An event leaderboard row.

EventScores pydantic-model

Bases: EmpireModel

A page of an event's scoreboard.

Fields:

• event (Event)
• list_type (RankingType)
• league_id (int | None)
• total (int | None)
• scores (list[EventScore])

event pydantic-field

event: Event

The event

list_type pydantic-field

list_type: RankingType

The board read

league_id pydantic-field

league_id: int | None

The league the page is from, as the server answered; None for none

total pydantic-field

total: int | None = None

Ranked entries on the whole board (its last rank); None when not given

scores pydantic-field

scores: list[EventScore]

The page's rows, in rank order

from_highscore classmethod

from_highscore(event: Event, list_type: RankingType, reply: GetHighscoreResponse) -> EventScores

A hgh reply.

A reply for another of the event's boards is read as that board, as the dialogs adopt the list a reply names.

Raises:

Type	Description
ReplyMismatchError	The reply is for a list that is not one of the event's, e.g. a late reply to another hgh request

Client: CastleGenericRankingComponent.onGetHighscoreData (bundle line 29601) ignores a reply for another list

from_leaderboard classmethod

from_leaderboard(event: Event, list_type: RankingType, reply: GetRankingListResponse) -> EventScores

A llsp or llsw reply.

ReadOnlyDict

Bases: dict[_K, _V]

A dict that refuses changes, so an event model handed out never changes.

Attributes:

Name	Type	Description
clear
pop
popitem
setdefault
update

clear class-attribute instance-attribute

clear = _refuse

pop class-attribute instance-attribute

pop = _refuse

popitem class-attribute instance-attribute

popitem = _refuse

setdefault class-attribute instance-attribute

setdefault = _refuse

update class-attribute instance-attribute

update = _refuse

EventPart pydantic-model

Bases: _ScoreFields

One score of an event with several: an invasion's player or alliance score, or a raid's own score.

Client: ALeagueTypeScoreEventVO.parseBasicsFromParamObject (bundle line 10260) over AScoreEventVO.parseBasicsFromParamObject (bundle line 14967), defaults at bundle line 14965; AScoreEventVO.setRankAndPoints (bundle line 15044) for a pep

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• reward_set_id (int)

reward_set_id pydantic-field

reward_set_id: int = 0

Wire key RSID

The reward set

parse classmethod

parse(entry: Any, previous: EventPart | None = None, sub_type: int = 0) -> EventPart

A part read from its entry, over previous when the client keeps the part.

SpecialEvent pydantic-model

Bases: EmpireModel

A running event, as its sei (or tei) entries left it.

Events the library has no class for keep only these fields and the entries in raw.

Client: ASpecialEventVO (bundle lines 2953-3049): parseBasicsFromParamObject (bundle line 2958) sets the end from RS when it is truthy, isActive (bundle line 3039); SpecialEventSeasonLeagueComponent.parseServerData (bundle line 64551) reads KL

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True, populate_by_name=True)

is_trigger class-attribute

is_trigger: bool = False

Whether the event is a trigger event (tei): the kingdoms league or a global effect event.

event_id pydantic-field

event_id: int

Wire key EID

The event's id

event pydantic-field

event: Event | None = None

The event, None for an id the event table lacks

end_time pydantic-field

end_time: float = 0.0

When the event ends, in time.monotonic() seconds; inf while it has no end

updated_at pydantic-field

updated_at: float = 0.0

When an entry for the event was last applied, wall clock

kingdoms_league_mode pydantic-field

kingdoms_league_mode: bool = False

Wire key KL

Whether the event runs in the kingdoms league's season mode

raw pydantic-field

raw: _Raw

The event's entries merged, the last one's keys winning; read-only, lists as tuples

remaining_seconds

remaining_seconds(now: float | None = None) -> float

Seconds until the event ends, 0 once it has.

is_active

is_active(now: float | None = None) -> bool

Whether the event has not ended yet.

from_entry classmethod

from_entry(event_id: int, entry: dict[str, Any], previous: SpecialEvent | None, now: float, events: Mapping[int, SpecialEvent]) -> SpecialEvent

The event an entry makes of previous, or of nothing for a new event.

Fields the entry reads only when it has them keep their value from previous; events are the other running events.

accepts classmethod

accepts(entry: dict[str, Any]) -> bool

Whether the client reads the entry at all, rather than failing on it and leaving the event as it was.

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

The event after a pep with these OR, OP and PT; unchanged for an event without a score.

ScoredEvent pydantic-model

Bases: SpecialEvent, _ScoreFields

An event with a score of your own.

Client: AScoreEventVO.parseBasicsFromParamObject (bundle line 14967), defaults at bundle line 14965; setRankAndPoints (bundle line 15044) for a pep

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)

difficulty_id pydantic-field

difficulty_id: int = -1

Wire key EDID

The difficulty chosen, -1 before one is; 0 without difficulty scaling

difficulty_scaling pydantic-field

difficulty_scaling: bool = False

Wire key EASE

Whether the event scales its difficulty

parts pydantic-field

parts: _Parts

The event's scores by their entry key; read-only

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

PointEvent pydantic-model

Bases: ScoredEvent

The nobility contest, and the base of LuckyWheelEvent: the lucky wheels keep the same score (LuckyWheelEventVO holds a LuckyWheelPointEventTypeScoreEventVO, an APointEventTypeScoreEventVO; bundle lines 59673, 117131).

Client: APointEventTypeScoreEventVO.parseBasicsFromParamObject (bundle line 59997)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• point_event_type (int)

point_event_type pydantic-field

point_event_type: int = -1

Wire key PET

Which contest it is

LeagueScoredEvent pydantic-model

Bases: ScoredEvent

A score event whose rewards come from a reward set.

Client: ALeagueTypeScoreEventVO.parseBasicsFromParamObject (bundle line 10260)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• reward_set_id (int)

reward_set_id pydantic-field

reward_set_id: int = 0

Wire key RSID

The reward set

BeggingKnightsEvent pydantic-model

Bases: LeagueScoredEvent

The marauders' contest.

Client: BeggingKnightsEventVO.parseBasicsFromParamObject (bundle line 114780)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• reward_set_id (int)
• total_hours (int)

total_hours pydantic-field

total_hours: int = 0

Wire key TH

The contest's length in hours

LongTermPointEvent pydantic-model

Bases: LeagueScoredEvent

The grand nobility prize.

Client: LongTermPointEventEventVO.parseParamObject (bundle line 116555)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• reward_set_id (int)
• upcoming_event_ids (tuple[EnumOrInt['Event'], ...])

upcoming_event_ids pydantic-field

upcoming_event_ids: tuple[EnumOrInt['Event'], ...] = ()

Wire key UE

The events whose points count towards it

GachaEvent pydantic-model

Bases: LeagueScoredEvent

A gacha event.

Client: AGachaEventVO.parseGachaEvent (bundle line 15371)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• reward_set_id (int)
• free_chest_reset_time (float)

free_chest_reset_time pydantic-field

free_chest_reset_time: float = 0.0

Wire key FCRT

When the free chest comes back, in time.monotonic() seconds

InvasionEvent pydantic-model

Bases: ScoredEvent

An invasion: its player and alliance scores are its parts.

Client: SamuraiInvasionEventVO.parseData (bundle line 55680) and FactionInvasionEventVO.parseData (bundle line 116044) rebuild every part from every entry; setRankAndPoints (bundle lines 55701, 116056) give a pep's first rank and points to the first part, and so on

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

SamuraiInvasionEvent pydantic-model

Bases: InvasionEvent

The samurai invasion. Client: SamuraiInvasionEventVO.parseData (bundle line 55680)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)

FactionInvasionEvent pydantic-model

Bases: InvasionEvent

The Berimond invasion: FB and FR are the blue and red players' scores, A the alliance's.

Client: FactionInvasionEventVO.parseData (bundle line 116044), setRankAndPoints (bundle line 116056)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)

AlienInvasionEvent pydantic-model

Bases: InvasionEvent

The war of the realms (71) and the Bloodcrow invasion (103); a part is rebuilt only from an entry that has it.

Client: AAlienInvasionEventVO.parseData and parseParamObject (bundle lines 58910, 58918), setRankAndPoints (bundle line 58926)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• target_zone_id (int)
• source_zone_id (int)
• use_reroll (bool)
• reroll_currency_keys (tuple[str, ...])

target_zone_id pydantic-field

target_zone_id: int = 0

Wire key TZID

The zone the invasion targets

source_zone_id pydantic-field

source_zone_id: int = 0

Wire key SZID

The zone the invasion comes from

use_reroll pydantic-field

use_reroll: bool = False

Wire key CRE

Whether camps can be rerolled

reroll_currency_keys pydantic-field

reroll_currency_keys: tuple[str, ...] = ()

Wire key RCKS

The currencies a reroll costs

NomadInvasionEvent pydantic-model

Bases: InvasionEvent

The nomad invasion: SP and A (rebuilt from an entry that has them) and, while the khan camp runs (ACE), the camp's score AC.

The client shows the khan camp's level (from the items' allianceInvasionCamps row of khan_camp_id) as that part's points; the state has no game data, so parts["AC"] keeps the points the entry sent.

Client: AllianceNomadInvasionEventVO.parseData (bundle lines 114287-114288), whose constructor (bundle line 114286) starts both scores; setRankAndPoints (bundle line 114310)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• alliance_rage (int)
• player_rage (int)
• player_total_rage (int)
• khan_camp_id (int | None)

alliance_rage pydantic-field

alliance_rage: int = 0

The khan camp's alliance rage

player_rage pydantic-field

player_rage: int = 0

Your current rage points on the khan camp

player_total_rage pydantic-field

player_total_rage: int = 0

Your total rage points on the khan camp

khan_camp_id pydantic-field

khan_camp_id: int | None = None

The khan camp, None before one is sent

BerimondEvent pydantic-model

Bases: SpecialEvent

Battle for Berimond. Your rank and points come only from pep pushes and start over with each entry.

Client: FactionEventVO.parseData (bundle line 7354) builds the league scores anew, parseParamObject and loadFactionDataFromParamObject (bundle lines 7364-7365), the defaults at bundle line 7353; setRankAndPoints (bundle line 7461)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• league_id (int)
• unlocked (bool)
• reward_set_id (int)
• own_rank (int)
• own_points (int)
• faction_id (int)
• main_camp_id (int)
• faction_protection_status (int)
• faction_protection_end (float | None)
• beginner_protection_end (float)

league_id pydantic-field

league_id: int = 1

Wire key LID

Your league

unlocked pydantic-field

unlocked: bool = False

Wire key UL

Whether Berimond is open to you

reward_set_id pydantic-field

reward_set_id: int = 0

Wire key RSID

The reward set

own_rank pydantic-field

own_rank: int = -1

Your rank, -1 while unranked; from the pep pushes

own_points pydantic-field

own_points: int = 0

Your points, from the pep pushes

faction_id pydantic-field

faction_id: int = 0

Your faction

main_camp_id pydantic-field

main_camp_id: int = 0

Your faction's main camp

faction_protection_status pydantic-field

faction_protection_status: int = 0

Your faction protection's status

faction_protection_end pydantic-field

faction_protection_end: float | None = 0.0

When your faction protection ends, in time.monotonic() seconds

beginner_protection_end pydantic-field

beginner_protection_end: float = 0.0

When your beginner protection ends, in time.monotonic() seconds

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

RaidBossEvent pydantic-model

Bases: SpecialEvent

The alliance raid boss: score is your own score, the alliance's is in alliance_points.

Client: AllianceRaidbossEventEventVO.parseData and parseParamObject (bundle lines 9109-9110), defaults at bundle line 9108; setRankAndPoints (bundle line 9117); PEPCommand.exec (bundle lines 128215-128216) for BLPP

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• score (EventPart)
• league_id (int)
• alliance_points (int)
• alliance_rank (int)
• subdivision_id (int)
• division_round_id (int)
• raid_boss_ids (tuple[EnumOrInt['RaidBoss'], ...])
• boss_level_points (int)

score pydantic-field

score: EventPart

Your score; its points are the entry's SP.OP

league_id pydantic-field

league_id: int = 0

Your alliance's league, from the entry's A

alliance_points pydantic-field

alliance_points: int = 0

Your alliance's points, from the entry's A and the pep pushes

alliance_rank pydantic-field

alliance_rank: int = 0

Your alliance's rank, from the pep pushes

subdivision_id pydantic-field

subdivision_id: int = 0

Your alliance's subdivision, from the entry's A

division_round_id pydantic-field

division_round_id: int = 0

Wire key DRI

The division round

raid_boss_ids pydantic-field

raid_boss_ids: tuple[EnumOrInt['RaidBoss'], ...] = ()

Wire key RBIDS

The bosses that can be fought

boss_level_points pydantic-field

boss_level_points: int = 0

Wire key BLPP

The points on the current boss level

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

TempServerEvent pydantic-model

Bases: SpecialEvent

A temporary server.

Client: TempServerEventVO.parseParamObject (bundle line 118162), defaults at bundle line 118161

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• daily_reset_time (float)
• setting_id (int | None)
• castle_bought (bool)
• is_cross_play (bool)

daily_reset_time pydantic-field

daily_reset_time: float = 0.0

Wire key RD

When the daily scores reset, in time.monotonic() seconds

setting_id pydantic-field

setting_id: int | None = None

Wire key TSID

The server's settings

castle_bought pydantic-field

castle_bought: bool = False

Wire key IPS

Whether you have a castle there

is_cross_play pydantic-field

is_cross_play: bool = False

Wire key ICSE

Whether the server is a cross-play one

DonationEvent pydantic-model

Bases: SpecialEvent

Imperial patronage.

Client: DonationEventEventVO.parseParamObject (bundle line 115502)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• setting_id (int | None)
• leaderboard_reward_set_id (int | None)

setting_id pydantic-field

setting_id: int | None = None

Wire key DSI

The donation settings

leaderboard_reward_set_id pydantic-field

leaderboard_reward_set_id: int | None = None

Wire key LRSI

The leaderboard's reward set

KingdomsLeagueEvent pydantic-model

Bases: SpecialEvent

The kingdoms league, a trigger event. It runs while it has more than a day left; on its last day it ends with the season event (the running event with kingdoms_league_mode), and without one it runs on at one day and has ended at none.

Client: SeasonLeagueEventVO.parseParamObject and endTimestamp (bundle lines 118059-118063), SeasonLeagueData.getActiveSeasonEventVO (bundle line 142582)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• remaining_days (int)
• original_days (int)
• reward_set_id (int)
• has_alliance_ranking (bool)
• league_type_id (int)

is_trigger class-attribute instance-attribute

is_trigger = True

remaining_days pydantic-field

remaining_days: int = 0

Wire key KLRD

Days left

original_days pydantic-field

original_days: int = 0

Wire key KLRT

The league's length in days

reward_set_id pydantic-field

reward_set_id: int = 0

Wire key RSID

The reward set

has_alliance_ranking pydantic-field

has_alliance_ranking: bool = False

Wire key KLARE

Whether alliances are ranked too

league_type_id pydantic-field

league_type_id: int = 0

Wire key KLLID

The league type

end_with

end_with(events: Mapping[int, SpecialEvent], now: float) -> float

When the league ends while events run.

remaining_seconds

remaining_seconds(now: float | None = None) -> float

Seconds until the league ends; its days left while it has no end.

GlobalEffectTimer pydantic-model

Bases: EmpireModel

One global effect of a global effect event.

Fields:

• effect_id (EnumOrInt['GlobalEffect'])
• end_time (float)
• strength (int)
• seen (bool)

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True, populate_by_name=True)

effect_id pydantic-field

effect_id: EnumOrInt['GlobalEffect']

The global effect

end_time pydantic-field

end_time: float

When it ends, in time.monotonic() seconds

strength pydantic-field

strength: int

Its strength, -1 for the effect's own

seen pydantic-field

seen: bool

Whether you have seen it

GlobalEffectEvent pydantic-model

Bases: SpecialEvent

The global effects running, a trigger event that ends with the last of them.

Client: GlobalEffectEventVO.parseParamObject (bundle lines 116399-116413)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• effects (tuple[GlobalEffectTimer, ...])
• seen_effect_ids (tuple[EnumOrInt['GlobalEffect'], ...])

is_trigger class-attribute instance-attribute

is_trigger = True

effects pydantic-field

effects: tuple[GlobalEffectTimer, ...] = ()

Wire key GE

The effects

seen_effect_ids pydantic-field

seen_effect_ids: tuple[EnumOrInt['GlobalEffect'], ...] = ()

Wire key SGE

The effects you have seen

accepts classmethod

accepts(entry: dict[str, Any]) -> bool

GlobalEffectBoost pydantic-model

Bases: EmpireModel

A global effect a boost event can strengthen.

Fields:

• effect_id (EnumOrInt['GlobalEffect'])
• boost_value (float)
• cost (int)

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True, populate_by_name=True)

effect_id pydantic-field

effect_id: EnumOrInt['GlobalEffect']

Wire key GEID

The global effect

boost_value pydantic-field

boost_value: float

Wire key BV

How much the boost adds

cost pydantic-field

cost: int

Wire key C2

The boost's price in rubies

GlobalEffectBuffEvent pydantic-model

Bases: SpecialEvent

The global effect boost, a trigger event that ends when the global effect event running as it arrived ends (at once without one).

Client: GlobalEffectBuffEventVO.parseParamObject (bundle lines 116381-116383), getBoostValues (bundle line 116384)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• boosts (tuple[GlobalEffectBoost, ...])

is_trigger class-attribute instance-attribute

is_trigger = True

boosts pydantic-field

boosts: tuple[GlobalEffectBoost, ...] = ()

Wire key GEB

The effects it boosts

boost_value

boost_value(effect_id: GlobalEffect | int) -> float

What the boost adds to a global effect's strength: the first matching boost's, 0 for one it lists none for.

Client: GlobalEffectBuffEventVO.getBoostValueForGlobalEffect (bundle line 116390)

AllianceTournamentEvent pydantic-model

Bases: ScoredEvent

The alliance tournament: your own score, and your alliance's in parts["A"], which the pep pushes update.

Client: AlliTournamentEventVO.parseData (bundle line 114401) reads A into its ALeagueTypeScoreEventVO (kept from entry to entry), setRankAndPoints (bundle line 114412)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)

accepts classmethod

accepts(entry: dict[str, Any]) -> bool

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

AllianceMobilizationEvent pydantic-model

Bases: ScoredEvent

The alliance mobilisation: parts["SP"] is your score and parts["A"] your alliance's, both rebuilt from every entry in the league of A.LID with the entry's RSID.

The client keeps an alliance score per league of the event's league types, and none for a league outside them; the state has no game data, so it keeps the one for your league whenever A.LID is 1 or more.

Client: AllianceMobilizationEventEventVO.parseData (bundle lines 5074-5081), setRankAndPoints (bundle line 5101)

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• subdivision_id (int)
• division_round_id (int)

subdivision_id pydantic-field

subdivision_id: int = 0

Your alliance's subdivision, from the entry's A

division_round_id pydantic-field

division_round_id: int = 0

Wire key DRI

The division round

accepts classmethod

accepts(entry: dict[str, Any]) -> bool

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

LuckyWheelEvent pydantic-model

Bases: PointEvent

The lucky wheel (15) and the sale days lucky wheel (89): a point event score and the wheel's state.

The client keeps the wheel's win class and its progress as sent; the library reads them as numbers.

Client: LuckyWheelEventVO.parseData, parseParamObject and setRankAndPoints (bundle lines 59674, 59686, 59687), LuckyWheelData.parseBasics (bundle line 17562); SaleDaysLuckyWheelEventVO (bundle line 117842) reads the same

Fields:

• league_id (int)
• own_rank (int)
• own_points (int)
• max_points (int)
• sub_type (int)
• point_scale (int)
• leaderboard_reward_set_id (int)
• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• difficulty_id (int)
• difficulty_scaling (bool)
• parts (_Parts)
• point_event_type (int)
• has_visited_pro_mode (bool)
• has_free_spin (bool)
• pro_mode (bool)
• win_class (int)
• win_class_progress (float)
• jackpot_set_id (int)
• jackpot_spin_set_id (int)

has_visited_pro_mode pydantic-field

has_visited_pro_mode: bool = False

Wire key HVPM

Whether you opened the pro mode

has_free_spin pydantic-field

has_free_spin: bool = False

Wire key HFS

Whether a free spin is waiting

pro_mode pydantic-field

pro_mode: bool = False

Wire key PMA

Whether the pro mode is on

win_class pydantic-field

win_class: int = 0

Wire key CWC

The wheel's current win class

win_class_progress pydantic-field

win_class_progress: float = 0.0

Wire key WCP

The progress towards the next win class

jackpot_set_id pydantic-field

jackpot_set_id: int = 0

Wire key JSID

The next jackpot set

jackpot_spin_set_id pydantic-field

jackpot_spin_set_id: int = 0

Wire key JHID

The jackpot set of the next jackpot spin

with_points

with_points(ranks: Any, points: Any, maxima: Any) -> SpecialEvent

ArtifactEvent pydantic-model

Bases: SpecialEvent

An artifact event: the parts of the artifact you have found.

Client: ArtifactEventVO.parseBasicsFromParamObject and parseParamObject (bundle lines 59141, 59161)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• artifact_league_id (int)
• parts_found (int)
• skin_id (int)

artifact_league_id pydantic-field

artifact_league_id: int = 0

Wire key ALID

Your artifact league

parts_found pydantic-field

parts_found: int = 0

Wire key PF

The artifact parts you have found

skin_id pydantic-field

skin_id: int = 0

Wire key SID

The event's skin

SeasonEvent pydantic-model

Bases: SpecialEvent

A season event: the Thornking (2), the Sea Queen (4) or the Underworld (64).

Client: ASeasonEventVO.parseParamObject (bundle line 31376); ThornkingEventVO, SeaqueenEventVO and UnderworldEventVO.parseParamObject (bundle lines 118454, 117975, 118678) read UL.MID first, the Thornking's through int() and the others' as sent; the library reads every one through int()

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• unlocked (bool)
• reward_id (int | None)
• finished (bool)
• map_id (int | None)

unlocked pydantic-field

unlocked: bool = False

Whether the event is open to you, from UL.UL

reward_id pydantic-field

reward_id: int | None = None

Wire key RID

The reward the event's end gives

finished pydantic-field

finished: bool = False

Wire key F

Whether you have finished the event

map_id pydantic-field

map_id: int | None = None

The event's treasure map, from UL.MID

FameBoosterEvent pydantic-model

Bases: SpecialEvent

The fame booster. Client: FameboosterEventVO.parseParamObject (bundle line 116103)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• bonus_percent (int)

bonus_percent pydantic-field

bonus_percent: int = 0

Wire key GBP

The extra glory, in percent

AllianceBonusEvent pydantic-model

Bases: SpecialEvent

An alliance payment bonus: the prime alliance bonus (45) or the alliance payment bonus (55).

Client: PrimeAlliBonusEventVO and AlliPaymentBonusEventVO.parseParamObject (bundle lines 117469, 114367)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• bonus_percent (int)

bonus_percent pydantic-field

bonus_percent: int = 0

Wire key APP

The bonus, in percent

DiscountSaleEvent pydantic-model

Bases: SpecialEvent

A prime sale with one discount: the relic enchanter sale (88) or the season pass sale (599).

Client: RelicEnchanterPrimeSaleEventVO and SeasonPassPrimeSaleEventVO.parseParamObject (bundle lines 117746, 118084)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• discount (int)

discount pydantic-field

discount: int = 0

Wire key DIS

The discount, in percent

SkipForFreeEvent pydantic-model

Bases: SpecialEvent

Free skips. Client: SkipForFreeEventVO.parseParamObject (bundle line 118150)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• free_skip_seconds (int)

free_skip_seconds pydantic-field

free_skip_seconds: int = 0

Wire key SEC

A wait this long or shorter is skipped for free

GiftEvent pydantic-model

Bases: SpecialEvent

The Goodgame gift. Client: GGSGiftEventVO.parseParamObject (bundle line 116370)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• collected (bool)
• skin_id (int | None)

collected pydantic-field

collected: bool = False

Wire key AC

Whether you have collected the gift

skin_id pydantic-field

skin_id: int | None = None

Wire key SID

The gift's skin, None before one is sent

FortuneTellerEvent pydantic-model

Bases: SpecialEvent

The fortune teller. Client: FortuneTellerEventVO.parseParamObject (bundle line 116134)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• tries (int)
• daily_reset_time (float | None)

tries pydantic-field

tries: int = 0

Wire key FTDC

Today's readings

daily_reset_time pydantic-field

daily_reset_time: float | None = None

Wire key STR

When the readings reset, in time.monotonic() seconds; None without STR

TournamentRank pydantic-model

Bases: EmpireModel

One place of the tournament of fame's ranking: [rank, fame points, owner record].

Client: TournamentEventVO.parseParamObject (bundle line 118596), CastleOtherPlayerData.parseOwnerInfo (bundle line 138996), which reads nothing from a record without an OID

Fields:

• rank (int)
• fame_points (int)
• owner (MapObject | None)

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True)

rank pydantic-field

rank: int

The place

fame_points pydantic-field

fame_points: int

The fame the player has earned, read through int()

owner pydantic-field

owner: MapObject | None = None

The player; None for a record without an OID

from_row classmethod

from_row(row: list[Any]) -> TournamentRank

A ranking row; a missing fame or owner reads as 0 or None.

TournamentEvent pydantic-model

Bases: SpecialEvent

The tournament of fame: the ranking, your place and the fame you have earned.

Client: TournamentEventVO.parseParamObject (bundle lines 118593-118598)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• own_rank (int)
• own_fame_points (int)
• booby_prize_min_fame (int)
• ranking (tuple[TournamentRank, ...])

own_rank pydantic-field

own_rank: int = 0

Wire key OR

Your rank

own_fame_points pydantic-field

own_fame_points: int = 0

Wire key OEP

The fame you have earned

booby_prize_min_fame pydantic-field

booby_prize_min_fame: int = 0

Wire key MFB

The fame the consolation prize needs

ranking pydantic-field

ranking: tuple[TournamentRank, ...] = ()

Wire key R

The ranking by place; an entry's rows replace the places they name, the others stay

CampaignEvent pydantic-model

Bases: SpecialEvent

A time-limited campaign: its quests, in the order they open, and its end reward.

A cqs push reads its campaign over it again (see with_campaign). The client turns RIDS into the rewards' collectables at once (rewardData.getListByIdArray); the game data is loaded only on request here, so the ids are kept, and rewards gives the same list.

Client: TimeLimitedCampaignEventEventVO.parseParamObject and sortByOrder (bundle lines 118536-118549), which sorts by ST and then CQID, a quest without ST last

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• reward_ids (tuple[RewardId, ...])
• reward_collected (bool)
• end_reward_value (int)
• quests (tuple[Quest, ...])

reward_ids pydantic-field

reward_ids: tuple[RewardId, ...] = ()

Wire key RIDS

The campaign's rewards; GameData.reward_list gives what they hold

reward_collected pydantic-field

reward_collected: bool = False

Wire key COL

Whether you collected the end reward

end_reward_value pydantic-field

end_reward_value: int = 0

Wire key ERV

The end reward's value

quests pydantic-field

quests: tuple[Quest, ...] = ()

Wire key CQS

The campaign's quests, in campaign order

rewards

rewards(data: GameData) -> tuple[Collectable, ...]

What the campaign's rewards give, in order, as the client lists them.

Client: getListByIdArray(e.RIDS) (TimeLimitedCampaignEventEventVO.parseParamObject, bundle line 118536)

with_campaign

with_campaign(data: dict[str, Any], now: float) -> CampaignEvent

The event after a cqs push with this payload. Client: parseCQS (bundle line 118555)

CampaignQuestEvent pydantic-model

Bases: SpecialEvent

The time-limited campaign's quest event; its end is the end of the campaign quests it names.

Client: TimeLimitedCampaignQuestEventEventVO.parseParamObject (bundle line 118576); CastleQuestVO.remainingSeconds (bundle line 52592)

Fields:

• event_id (int)
• event (Event | None)
• end_time (float)
• updated_at (float)
• kingdoms_league_mode (bool)
• raw (_Raw)
• quest_ids (tuple[EnumOrInt['QuestId'], ...])

quest_ids pydantic-field

quest_ids: tuple[EnumOrInt['QuestId'], ...] = ()

Wire key CQS

The campaign quests it times, each QID read through int()

accepts classmethod

accepts(entry: dict[str, Any]) -> bool

SpecialEventInfoRequest pydantic-model

Bases: BaseRequest

Ask for the running events; the server answers with a sei.

Command: sei Payload: {}

Client: C2SSpecialEventInfoVO (bundle lines 37406-37407), which has no fields; sent after a temporary server castle is bought (bundle line 24305)

GetEventPointsRequest pydantic-model

Bases: BaseRequest

Ask for your rank and points in a running event; the server answers with a pep.

Command: pep Payload: {"EID": event_id}

Client: C2SPointEventGetPointsVO (bundle lines 8697-8698), sent as an event's dialog opens (e.g. CastlePointEventDialog, bundle line 117419; FactionEventRankingsSublayer.show, bundle line 95328) and after a marauders' contest payment (BKPCommand, bundle line 128199)

Fields:

• event_id (int)

event_id pydantic-field

event_id: int

Wire key EID

The event, e.g. Event.POINT_EVENT

accepts_reply

accepts_reply(payload: Any) -> bool

Whether a pep reply is about this event: its EID, when sent, is the one asked for.

Client: PEPCommand.exec (bundle line 128213) applies a reply to the event its EID names

GetEventPointsResponse pydantic-model

Bases: BaseResponse

Your rank and points in an event, pushed as you score and sent in answer to a GetEventPointsRequest.

OR, OP and PT are lists, one value per score the event keeps, in this order:

• a score event (nobility contest, marauders, long-term points, gacha): your own (AScoreEventVO.setRankAndPoints, bundle line 15044)
• the alliance tournament: your alliance's, the first only (AlliTournamentEventVO, bundle line 114412)
• Berimond and the lucky wheel: your own, the first only (FactionEventVO, bundle line 7461, into your league; LuckyWheelEventVO, bundle line 59687)
• the alien, red alien, nomad and samurai invasions and the alliance mobilisation: yours, then your alliance's; PT may be sent, these events do not read it (bundle lines 58926, 114310, 55701, 5101)
• the Berimond invasion: blue players, red players, then your alliance, PT per part (bundle line 116056)
• the alliance raid boss: yours, then your alliance's (bundle line 9117), and BLPP

Client: PEPCommand.exec (bundle lines 128213-128216), which hands the lists to the event's setRankAndPoints; the state applies them the same way (client.state.get_event)

Fields:

• error_code (int)
• event_id (ClientInt)
• own_ranks (list[ClientInt])
• own_points (list[ClientInt])
• max_points (list[ClientInt] | None)
• boss_level_points (ClientInt | None)

event_id pydantic-field

event_id: ClientInt

Wire key EID

The event

own_ranks pydantic-field

own_ranks: list[ClientInt]

Wire key OR

Your ranks, one per score in the order above; -1 unranked

own_points pydantic-field

own_points: list[ClientInt]

Wire key OP

Your points, one per score in the order above

max_points pydantic-field

max_points: list[ClientInt] | None = None

Wire key PT

The most points each score counts; None when not sent

boss_level_points pydantic-field

boss_level_points: ClientInt | None = None

Wire key BLPP

The points on the raid boss's current level; None for other events

GameEvent pydantic-model

Bases: EmpireModel

A running event with its in-game title.

Fields:

• event_id (int)
• event (Event | None)
• display_name (str)
• details (SerializeAsAny[SpecialEvent])

model_config class-attribute

model_config: ConfigDict = ConfigDict(frozen=True)

event_id pydantic-field

event_id: int

The event's id

event pydantic-field

event: Event | None = None

The event, None for an id the event table lacks

display_name pydantic-field

display_name: str

The in-game title; without one, the event's Event name, or its id for an unknown event

details pydantic-field

details: SerializeAsAny[SpecialEvent]

The running event, as client.state.get_event() gives it, dumped with its own fields

event_class

event_class(event_id: int) -> type[SpecialEvent]

The model an event's entries are read into.

events.titles

The in-game titles of the server's events, from the game's language file.

Usage

titles = get_event_titles("de")
titles.get(83)  # the long-term point event's title

The titles are cosmetic: a CDN outage gives the titles last fetched, or none, and is retried after a pause (see empire_core.texts.get_texts).

Functions:

Name	Description
get_event_titles	The in-game title of every event, by event id, in lang.

get_event_titles

get_event_titles(lang: str = 'en', force_refresh: bool = False) -> dict[int, str]

The in-game title of every event, by event id, in lang.

Fetched from the GGS language CDN and cached for 24 hours. A failed fetch gives the titles last fetched, or an empty dict, and is not retried for five minutes.

Parameters:

Name	Type	Description	Default
lang	str	Language code (default: "en")	'en'
force_refresh	bool	Fetch from the CDN even when the cached titles are fresh	False

Client: the event dialogs show "event_title_"+eventId (ASeasonEventVO.seasonNameString, bundle line 31389)