vehicle abilities and their characteristics

This commit is contained in:
tresabhi committed 2026-11-15 21:14:09 -06:00
1 parent 79129ff3c0
commit b48a68b8de
21 files changed
+1664 -258

No files matched your search

@@ -87,7 +87,7 @@ export abstract class ServerBlitzKitAPI0 extends AbstractBlitzKitAPI {
protected botPattern = /^.+((tutorial_bot(\d+)?)|(TU))$/;
protected stringsI18n: Record<string, Record<string, string>> = {};
private stringsI18n: Record<string, Record<string, string>> = {};
protected nationsDir?: string[];
protected tankStringIdMap: Record<string, number> = {};
protected consumablesCommon: ConsumablesCommon = {};
@@ -1,25 +1,53 @@
import { ConsumablesCommon, OptionalDevices } from "../../../types";
import { BlitzEffectScript } from "../../../types/blitzEffectScript";
import { BlitzScripts } from "../../../types/blitzScripts";
import type {
BlitzEffectScript,
BlitzScripts,
ConsumablesCommon,
OptionalDevices,
} from "../../../types";
import { AbstractVFS } from "../../vfs";
import { Cache } from "./0_base";
import { ServerBlitzKitAPI10 } from "./10_avatars";
function assignNormalizedScript(
target: Record<string, BlitzEffectScript>,
key: number,
script?: BlitzEffectScript,
) {
if (script === undefined) return;
export abstract class ServerBlitzKitAPI11 extends ServerBlitzKitAPI10 {
// The XML parser keeps switches as text, but the script types declare them as
// booleans
private normalizeSwitches<Value>(value: Value): Value {
if (typeof value === "string") {
const lowered = value.toLowerCase();
if (script["#text"] === "StaticFactorDevice") {
script["#text"] = script.attribute!;
if (lowered === "true") return true as Value;
if (lowered === "false") return false as Value;
}
if (Array.isArray(value))
return value.map((child) => this.normalizeSwitches(child)) as Value;
if (typeof value === "object" && value !== null) {
return Object.fromEntries(
Object.entries(value).map(([key, child]) => [
key,
this.normalizeSwitches(child),
]),
) as Value;
}
return value;
}
target[key] = script;
}
private assignNormalizedScript(
target: Record<number, BlitzEffectScript>,
key: number,
script?: BlitzEffectScript,
) {
if (script === undefined) return;
if (script["#text"] === "StaticFactorDevice") {
script["#text"] = script.attribute!;
}
target[key] = this.normalizeSwitches(script);
}
export abstract class ServerBlitzKitAPI11 extends ServerBlitzKitAPI10 {
@Cache()
async scripts() {
const scripts: BlitzScripts = {
@@ -35,14 +63,18 @@ export abstract class ServerBlitzKitAPI11 extends ServerBlitzKitAPI10 {
for (const key in optionalDevices.root) {
const equipment = optionalDevices.root[key];
assignNormalizedScript(scripts.equipment, equipment.id, equipment.script);
this.assignNormalizedScript(
scripts.equipment,
equipment.id,
equipment.script,
);
}
async function assign(
const assign = async (
vfs: AbstractVFS,
dir: string,
target: keyof BlitzScripts,
) {
target: "consumables" | "provisions",
) => {
const root = `Data/XML/item_defs/vehicles/common/${dir}`;
const list = await vfs.text(`${root}/list.xml`);
const pattern = /<items path="(\w+)\.xml"\/>/gm;
@@ -55,14 +87,14 @@ export abstract class ServerBlitzKitAPI11 extends ServerBlitzKitAPI10 {
for (const key in things.root) {
const thing = things.root[key];
assignNormalizedScript(
this.assignNormalizedScript(
scripts[target],
thing.id,
things.root[key].script,
);
}
}
}
};
await assign(this.vfs, "consumables", "consumables");
await assign(this.vfs, "provisions", "provisions");
+288 -162
View File
@@ -1,9 +1,11 @@
import {
type AugmentAttributeDefinitions,
BlitzCrewType,
BlitzModuleType,
blitzShellKindToBlitzkit,
BlitzTankClass,
ChassisDefinitionsList,
type ConsumablesVehicleFilter,
EngineDefinitionsList,
GunDefinitionsList,
ShellDefinitionsList,
@@ -17,10 +19,13 @@ import {
UpgradeProgressionXml,
UpgradeProgressionXmlNode,
UpgradeProgressionXmlRequirement,
type VehicleAbilityItem,
type VehicleDefinitionGun,
VehicleDefinitionList,
VehicleDefinitions,
} from "@blitzkit/core";
import {
AbilitySource,
AssaultRanges,
AugmentAttribute,
AugmentNode,
@@ -33,23 +38,282 @@ import {
ModulePosition,
ModuleType,
ResearchCost,
ShellDefinition,
TankDefinitions,
TankPrice,
TankPriceType,
TankType,
Unlock,
type VehicleAbility,
} from "@blitzkit/protos";
import { Cache, ServerBlitzKitAPI0 } from "./0_base";
// What an augment attribute shows, by attribute name
interface AugmentAttributeDefinition {
icon: string;
title: string;
}
type AugmentAttributeDefinitions = Map<string, AugmentAttributeDefinition>;
export abstract class ServerBlitzKitAPI1 extends ServerBlitzKitAPI0 {
// A gun the way a tank's turret or a vehicle ability builds it. `gun`
// overrides the shared gun entry, which is all an ability has
private parseGun(
nation: string,
gunKey: string,
gunList: GunDefinitionsList,
shellList: ShellDefinitionsList,
gun: Partial<VehicleDefinitionGun>,
unlocks: GunDefinition["unlocks"],
) {
const gunListEntry = gunList.shared[gunKey];
const gunType =
gun.clip === undefined
? "regular"
: gun.pumpGunMode
? "auto_reloader"
: "auto_loader";
const gunClipCount = gunType === "regular" ? 1 : gun.clip!.count;
const shotDispersionFactors =
gun.shotDispersionFactors ?? gunListEntry.shotDispersionFactors;
let assault_ranges: AssaultRanges | undefined;
if (gun.extras?.trayShell) {
const types = gun.extras.trayShell.kinds.split(" ").map((string) => {
const trimmed = string.trim();
if (trimmed in blitzShellKindToBlitzkit) {
return blitzShellKindToBlitzkit[trimmed as ShellKind];
}
throw new SyntaxError(`Invalid shell kind: ${trimmed}`);
});
const sectorNames = Object.keys(gun.extras.trayShell.sectors);
if (sectorNames.length !== 1 || sectorNames[0] !== "sector") {
throw new SyntaxError("Invalid tray shell sector");
}
const sector = gun.extras.trayShell.sectors.sector;
assault_ranges = {
types,
ranges: sector.map((value) => ({
factor: value.factor,
distance: value.distance,
})),
};
}
return {
id: toUniqueId(nation, gunList.ids[gunKey]),
weight: gunListEntry.weight,
rotation_speed: gunListEntry.rotationSpeed,
name: this.getString(gunListEntry.userString),
tier: gunListEntry.level,
shells: this.parseShells(nation, gunListEntry, shellList),
camouflage_loss:
gun.invisibilityFactorAtShot === undefined
? 0
: typeof gun.invisibilityFactorAtShot === "number"
? gun.invisibilityFactorAtShot
: gun.invisibilityFactorAtShot.at(-1)!,
aim_time: gun.aimingTime ?? gunListEntry.aimingTime,
dispersion_base:
gun.shotDispersionRadius ?? gunListEntry.shotDispersionRadius,
dispersion_damaged: shotDispersionFactors.whileGunDamaged,
dispersion_shot: shotDispersionFactors.afterShot,
dispersion_traverse: shotDispersionFactors.turretRotation,
unlocks,
shell_capacity: gun.maxAmmo ?? gunListEntry.maxAmmo,
assault_ranges,
burst:
gun.burst && gun.burst.count > 1
? {
count: gun.burst.count,
interval: 60 / gun.burst.rate,
}
: undefined,
gun_type:
gunType === "regular"
? {
$case: "regular",
value: {
reload: gun.reloadTime ?? 0,
},
}
: gunType === "auto_reloader"
? {
$case: "auto_reloader",
value: {
intra_clip: 60 / gun.clip!.rate,
shell_count: gunClipCount,
shell_reloads: gun.pumpGunReloadTimes!.split(" ").map(Number),
},
}
: {
$case: "auto_loader",
value: {
intra_clip: 60 / gun.clip!.rate,
clip_reload: gun.reloadTime ?? 0,
shell_count: gunClipCount,
},
},
} satisfies GunDefinition;
}
// The shells a gun fires. Its shots may override a shell's speed, range and
// penetration, and otherwise the shell's own values hold
private parseShells(
nation: string,
gunListEntry: GunDefinitionsList["shared"][string],
shellList: ShellDefinitionsList,
) {
return Object.keys(gunListEntry.shots ?? {}).map((shellKey) => {
const gunShellEntry = gunListEntry.shots[shellKey];
const shell = shellList[shellKey];
// Newer client data stores shot properties on the shell rather than
// repeating them under every gun's <shots> entry
const speed =
typeof gunShellEntry === "string" ? shell.speed : gunShellEntry.speed;
const maxDistance =
typeof gunShellEntry === "string"
? shell.maxDistance
: gunShellEntry.maxDistance;
const piercingPower =
typeof gunShellEntry === "string"
? shell.piercingPower
: gunShellEntry.piercingPower;
const penetrationRaw = piercingPower
.split(" ")
.filter((penetrationString) => penetrationString !== "")
.map(Number);
return {
id: toUniqueId(nation, shell.id),
name: this.getString(shell.userString),
velocity: speed,
armor_damage: shell.damage.armor,
module_damage: shell.damage.devices,
caliber: shell.caliber,
normalization: shell.normalizationAngle,
ricochet: shell.ricochetAngle,
type: blitzShellKindToBlitzkit[shell.kind],
explosion_radius:
shell.kind === "HIGH_EXPLOSIVE"
? shell.explosionRadius ?? 0
: undefined,
icon: shell.icon,
penetration: {
near: penetrationRaw[0],
far: penetrationRaw[1],
},
range: maxDistance,
acceleration: shell.acceleration,
max_speed: shell.maxSpeed,
} satisfies ShellDefinition;
});
}
// A vehicle ability's placeholder gun as `nation:gun`, built like a tank's own
// guns. An ability's gun has no turret, so its shared entry is all its data
private async placeholderGun(reference: string) {
const [nation, gunKey] = reference.trim().split(":");
const base = `Data/XML/item_defs/vehicles/${nation}/components`;
const { root: gunList } = await this.vfs.xml<{
root: GunDefinitionsList;
}>(`${base}/guns.xml`);
const { root: shellList } = await this.vfs.xml<{
root: ShellDefinitionsList;
}>(`${base}/shells.xml`);
const shared = gunList.shared[gunKey];
if (shared === undefined) {
throw new Error(`Vehicle ability gun ${reference} is not in guns.xml`);
}
return this.parseGun(nation, gunKey, gunList, shellList, shared, []);
}
// The hidden provisions and consumables the game marks as vehicle abilities,
// by the key a tank's `extras` names them with
private vehicleAbilityItems() {
const items = new Map<string, VehicleAbilityItem>();
const groups = [
[AbilitySource.ABILITY_SOURCE_CONSUMABLE, this.consumablesCommon],
[AbilitySource.ABILITY_SOURCE_PROVISION, this.provisionsCommon],
] as const;
for (const [source, group] of groups) {
for (const [key, item] of Object.entries(group)) {
if (!("isVehicleAbility" in item)) continue;
// The names in the filter's `include`, or nothing when it doesn't name tanks
const vehicle = item.vehicleFilter?.include.vehicle;
items.set(key, {
source,
id: item.id,
vehicleNames:
vehicle !== undefined && "name" in vehicle
? vehicle.name.trim().split(/\s+/)
: undefined,
gun: item.script?.gun,
});
}
}
return items;
}
// The abilities a tank has, from the hidden items its own `extras` names.
// Guns name none in the game files today, so one is an error, not a gap
private async vehicleAbilitiesOf(
nation: string,
tankKey: string,
root: {
extras?: Record<string, unknown>;
turrets0?: Record<
string,
{ guns: Record<string, { extras?: Record<string, unknown> }> }
>;
},
items: Map<string, VehicleAbilityItem>,
) {
const name = `${nation}:${tankKey}`;
for (const turret of Object.values(root.turrets0 ?? {})) {
for (const gun of Object.values(turret.guns ?? {})) {
for (const key of Object.keys(gun.extras ?? {})) {
if (items.has(key)) {
throw new Error(
`Gun extra ${key} on ${name} is a vehicle ability, which is only linked for tanks`,
);
}
}
}
}
const abilities: VehicleAbility[] = [];
for (const key of Object.keys(root.extras ?? {})) {
const item = items.get(key);
if (item === undefined) continue;
if (item.vehicleNames && !item.vehicleNames.includes(name)) {
throw new Error(
`${key} is on ${name}, which its vehicle filter does not include`,
);
}
abilities.push({
source: item.source,
id: item.id,
gun:
item.gun === undefined
? undefined
: await this.placeholderGun(item.gun),
});
}
return abilities;
}
private parseResearchCost(raw: number | string) {
if (typeof raw === "number") {
return {
@@ -194,6 +458,7 @@ export abstract class ServerBlitzKitAPI1 extends ServerBlitzKitAPI0 {
@Cache()
async tanks() {
const tankDefinitions = TankDefinitions.create();
const abilityItems = this.vehicleAbilityItems();
const gameModeNativeNames: Record<string, string> = {};
@@ -605,6 +870,12 @@ export abstract class ServerBlitzKitAPI1 extends ServerBlitzKitAPI0 {
dev_name: tankKey,
module_positions,
augment_progression,
vehicle_abilities: await this.vehicleAbilitiesOf(
nation,
tankKey,
tankDefinition.root,
abilityItems,
),
roles: {},
camouflages: camouflages,
fixed_camouflage: fixedCamouflage,
@@ -726,165 +997,20 @@ export abstract class ServerBlitzKitAPI1 extends ServerBlitzKitAPI0 {
),
});
let gunIndex = 0;
for (const gunKey in turret.guns) {
const gun = turret.guns[gunKey];
const gunId = toUniqueId(nation, gunList.root.ids[gunKey]);
const gunListEntry = gunList.root.shared[gunKey];
const gunName = this.getString(gunListEntry.userString);
const gunType =
"clip" in gun
? gun.pumpGunMode
? "autoReloader"
: "autoLoader"
: "regular";
const gunClipCount = gunType === "regular" ? 1 : gun.clip!.count;
const shotDispersionFactors =
gun.shotDispersionFactors ?? gunListEntry.shotDispersionFactors;
let assault_ranges: AssaultRanges | undefined;
if (gun.extras?.trayShell) {
const types = gun.extras.trayShell.kinds
.split(" ")
.map((string) => {
const trimmed = string.trim();
if (trimmed in blitzShellKindToBlitzkit) {
return blitzShellKindToBlitzkit[trimmed as ShellKind];
}
throw new SyntaxError(`Invalid shell kind: ${trimmed}`);
});
const sectorNames = Object.keys(gun.extras.trayShell.sectors);
if (sectorNames.length !== 1 || sectorNames[0] !== "sector") {
throw new SyntaxError("Invalid tray shell sector");
}
const sector = gun.extras.trayShell.sectors.sector;
assault_ranges = {
types,
ranges: sector.map((value) => ({
factor: value.factor,
distance: value.distance,
})),
};
}
totalUnlocks.push(gun.unlocks);
tankDefinitions.tanks[tankId].turrets[turretIndex].guns.push({
id: gunId,
weight: gunListEntry.weight,
rotation_speed: gunListEntry.rotationSpeed,
name: gunName,
tier: gunListEntry.level,
shells: [],
camouflage_loss:
typeof gun.invisibilityFactorAtShot === "number"
? gun.invisibilityFactorAtShot
: gun.invisibilityFactorAtShot.at(-1)!,
aim_time: gun.aimingTime ?? gunListEntry.aimingTime,
dispersion_base:
gun.shotDispersionRadius ?? gunListEntry.shotDispersionRadius,
dispersion_damaged: shotDispersionFactors.whileGunDamaged,
dispersion_shot: shotDispersionFactors.afterShot,
dispersion_traverse: shotDispersionFactors.turretRotation,
unlocks: resolveUnlocks(
this.blitzModuleTypeToBlitzkit,
gun.unlocks,
tankDefinitions.tanks[tankId].turrets[turretIndex].guns.push(
this.parseGun(
nation,
gunKey,
gunList.root,
shellList.root,
gun,
resolveUnlocks(this.blitzModuleTypeToBlitzkit, gun.unlocks),
),
shell_capacity: gun.maxAmmo ?? gunListEntry.maxAmmo,
assault_ranges,
burst:
gun.burst && gun.burst.count > 1
? {
count: gun.burst.count,
interval: 60 / gun.burst.rate,
}
: undefined,
gun_type:
gunType === "regular"
? {
$case: "regular",
value: {
reload: gun.reloadTime,
},
}
: gunType === "autoReloader"
? {
$case: "auto_reloader",
value: {
intra_clip: 60 / gun.clip!.rate,
shell_count: gunClipCount,
shell_reloads: gun
.pumpGunReloadTimes!.split(" ")
.map(Number),
},
}
: {
$case: "auto_loader",
value: {
intra_clip: 60 / gun.clip!.rate,
clip_reload: gun.reloadTime,
shell_count: gunClipCount,
},
},
} satisfies GunDefinition);
for (const shellKey in gunListEntry.shots) {
const gunShellEntry = gunListEntry.shots[shellKey];
const shell = shellList.root[shellKey];
// Newer client data stores shot properties on the shell rather
// than repeating them under every gun's <shots> entry.
const speed =
typeof gunShellEntry === "string"
? shell.speed
: gunShellEntry.speed;
const maxDistance =
typeof gunShellEntry === "string"
? shell.maxDistance
: gunShellEntry.maxDistance;
const piercingPower =
typeof gunShellEntry === "string"
? shell.piercingPower
: gunShellEntry.piercingPower;
const shellId = toUniqueId(nation, shell.id);
const shellName = this.getString(shell.userString);
const penetrationRaw = piercingPower
.split(" ")
.filter((penetrationString) => penetrationString !== "")
.map(Number);
tankDefinitions.tanks[tankId].turrets[turretIndex].guns[
gunIndex
].shells.push({
id: shellId,
name: shellName,
velocity: speed,
armor_damage: shell.damage.armor,
module_damage: shell.damage.devices,
caliber: shell.caliber,
normalization: shell.normalizationAngle,
ricochet: shell.ricochetAngle,
type: blitzShellKindToBlitzkit[shell.kind],
explosion_radius:
shell.kind === "HIGH_EXPLOSIVE"
? shell.explosionRadius ?? 0
: undefined,
icon: shell.icon,
penetration: {
near: penetrationRaw[0],
far: penetrationRaw[1],
},
range: maxDistance,
});
}
gunIndex++;
);
}
turretIndex++;
@@ -0,0 +1,10 @@
// What an augment attribute shows, by attribute name
export interface AugmentAttributeDefinition {
icon: string;
title: string;
}
export type AugmentAttributeDefinitions = Map<
string,
AugmentAttributeDefinition
>;
+8 -4
View File
@@ -4,6 +4,14 @@ export type BlitzEffectScript = RSN & {
cooldown?: number;
duration?: number;
aimingSpeed?: number;
gunDispersionModifier?: number;
activateWithoutDamage?: boolean;
targetOrder?: boolean;
// A placeholder gun the ability fires, as `nation:gun`, and what it resolves to
gun?: string;
allowSwitchAfterKill?: boolean;
allowNonDamagingHits?: boolean;
startCooldown?: number;
automatic?: boolean;
@@ -52,10 +60,6 @@ interface ModuleConstants {
modules: Record<string, number | number[]>;
}
interface ModulesMaxHPFactorsModules {
ammoBayHealth: number;
}
interface ChangesToHit {
crew: number;
modules: RSN;
+1 -1
View File
@@ -1,4 +1,4 @@
import { BlitzEffectScript } from "./blitzEffectScript";
import type { BlitzEffectScript } from "./blitzEffectScript";
export interface BlitzScripts {
consumables: Record<number, BlitzEffectScript>;
@@ -5,6 +5,7 @@ export interface GunDefinitionsList {
[key: string]: {
rotationSpeed: number;
weight: number;
reloadTime?: number;
shotDispersionFactors: {
turretRotation: number;
afterShot: number;
+5
View File
@@ -1,5 +1,8 @@
export * from "./augmentAttributeDefinitions";
export * from "./availableNationsYaml";
export * from "./blitzEffectScript";
export * from "./blitzModuleType";
export * from "./blitzScripts";
export * from "./blitzStrings";
export * from "./blitzTankFilterDefinitionCategory";
export * from "./camouflagesXml";
@@ -24,6 +27,8 @@ export * from "./tanksStats";
export * from "./techTreeLayoutYaml";
export * from "./turretDefinitionsList";
export * from "./upgradeProgressionXml";
export * from "./vehicleAbilityItem";
export * from "./vehicleDefinitionArmor";
export * from "./vehicleDefinitionList";
export * from "./vehicleDefinitions";
export * from "./vehicleFilter";
+19 -17
View File
@@ -1,20 +1,22 @@
export type ShellDefinitionsList = Record<
string,
{
id: number;
userString: string;
icon: string;
kind: ShellKind;
caliber: number;
damage: { armor: number; devices: number };
normalizationAngle?: number;
ricochetAngle?: number;
explosionRadius?: number;
speed: number;
maxDistance: number;
piercingPower: string;
}
> & {
// A shell as its shells.xml entry lists it
export interface ShellDefinitionXml {
id: number;
userString: string;
icon: string;
kind: ShellKind;
caliber: number;
damage: { armor: number; devices: number };
normalizationAngle?: number;
ricochetAngle?: number;
explosionRadius?: number;
speed: number;
maxDistance: number;
acceleration?: number;
maxSpeed?: number;
piercingPower: string;
}
export type ShellDefinitionsList = Record<string, ShellDefinitionXml> & {
icons: Record<string, string>;
};
@@ -0,0 +1,11 @@
import type { AbilitySource } from "@blitzkit/protos";
// A hidden provision or consumable the game marks as a vehicle ability.
// `vehicleNames` is its filter's list of tanks, when it has one
export interface VehicleAbilityItem {
source: AbilitySource;
id: number;
vehicleNames?: string[];
// The placeholder gun the ability fires, as `nation:gun`
gun?: string;
}
+45 -42
View File
@@ -78,48 +78,7 @@ export interface VehicleDefinitions {
collisionModel: string;
};
guns: {
[key: string]: {
unlocks: UnlocksListing;
armor: VehicleDefinitionArmor & {
gun?:
| number
| {
chanceToHitByProjectile: number;
chanceToHitByExplosion: number;
"#text": number;
};
};
invisibilityFactorAtShot: number | number[];
reloadTime: number;
aimingTime?: number;
shotDispersionRadius: number;
shotDispersionFactors?: {
turretRotation: number;
afterShot: number;
whileGunDamaged: number;
};
maxAmmo: number;
extraPitchLimits?: {
front?: string;
back?: string;
transition?: number | number[];
};
pitchLimits?: string | string[];
pumpGunMode?: boolean;
pumpGunReloadTimes?: string;
clip?: { count: number; rate: number };
burst?: { count: number; rate: number };
models: { undamaged: string };
extras?: {
trayShell?: {
kinds: string;
sectors: Record<
string,
{ id: number; distance: number; factor: number }[]
>;
};
};
};
[key: string]: VehicleDefinitionGun;
};
};
};
@@ -154,3 +113,47 @@ export type BlitzCrewType =
| "loader";
export type UnlocksListing = BlitzModuleType | undefined;
// A turret gun as its tank lists it, which overrides the shared gun entry
export interface VehicleDefinitionGun {
unlocks: UnlocksListing;
armor: VehicleDefinitionArmor & {
gun?:
| number
| {
chanceToHitByProjectile: number;
chanceToHitByExplosion: number;
"#text": number;
};
};
invisibilityFactorAtShot: number | number[];
reloadTime: number;
aimingTime?: number;
shotDispersionRadius: number;
shotDispersionFactors?: {
turretRotation: number;
afterShot: number;
whileGunDamaged: number;
};
maxAmmo: number;
extraPitchLimits?: {
front?: string;
back?: string;
transition?: number | number[];
};
pitchLimits?: string | string[];
pumpGunMode?: boolean;
pumpGunReloadTimes?: string;
clip?: { count: number; rate: number };
burst?: { count: number; rate: number };
models: { undamaged: string };
extras?: {
trayShell?: {
kinds: string;
sectors: Record<
string,
{ id: number; distance: number; factor: number }[]
>;
};
};
}
+3
View File
@@ -0,0 +1,3 @@
export interface VehicleFilter {
include?: { vehicle?: { name?: string } | { name?: string }[] };
}