doc/fans: new article for career fan gain formula

2026-10-17 14:25:57 -04:00
parent 888a6dbf3c
commit 939012b511
3 changed files with 491 additions and 0 deletions
@@ -0,0 +1,58 @@
+const margins = [
+	[0.75, 0.0, 0.09],
+	[2.5, 0.02, 0.06],
+	[4, 0.04, 0.04],
+	[6, 0.06, 0.02],
+	[Infinity, 0.09, 0.0],
+] as const;
+
+/**
+ * Calculate fans gained from a career race due to the margin of the finish.
+ * @param baseFans Base fans from the race and finish order
+ * @param finishOrder Placement of the trainee
+ * @param margin Margin in lengths between the trainee and second if a win, or the winner and trainee if a loss
+ * @returns Fans gained due to finish margin
+ */
+export function marginFans(baseFans: number, finishOrder: number, margin: number): number {
+	if (finishOrder > 3) {
+		return 0;
+	}
+	const [, wb, lb] = margins.find(([m]) => margin < m)!;
+	const b = finishOrder === 1 ? wb : lb;
+	return Math.floor(baseFans * b);
+}
+
+const skills = [
+	[0, 0.0],
+	[3, 0.02],
+	[6, 0.03],
+	[9, 0.05],
+	[Infinity, 0.08],
+] as const;
+
+/**
+ * Calculate the fans gained from a career race due to skills activated.
+ * @param baseFans Base fans from the race and finish order
+ * @param skillsActivated Number of skills the trainee activated during the race
+ * @returns Fans gained due to skill activations
+ */
+export function skillFans(baseFans: number, skillsActivated: number): number {
+	const [, b] = skills.find(([n]) => skillsActivated <= n)!;
+	return Math.floor(baseFans * b);
+}
+
+/**
+ * Calculate fan gain from a career race.
+ * @param baseFans Base fans from the race and finish order
+ * @param marginFans Fans gained due to finish margin
+ * @param skillFans Fans gained due to skill activations
+ * @param fanBonus Total fan bonus from support cards
+ * @param itemBonus Fan bonus from items (MANT glowsticks)
+ * @returns Total fans gained
+ */
+export function gained(baseFans: number, marginFans: number, skillFans: number, fanBonus: number, itemBonus?: number): number {
+	const f = baseFans + marginFans + skillFans;
+	const d = Math.round(f * (1 + fanBonus / 100));
+	const b = itemBonus ?? 0;
+	return Math.floor(d * (1 + b / 100));
+}