Skip to content

Wife3 Scoring System.hx

Jump to bottom
AutisticLulu edited this page Oct 22, 2025 · 8 revisions

Wife3 Scoring System.hx - API Reference

Wife3 (Wife version 3) is Etterna's timing-based accuracy algorithm.

This script provides comprehensive global callback functions accessible from any Lua or HScript.

📖 Table of Contents

Configuration Functions

wife3_enabled(enabled: Bool)

Enable or disable Wife3 scoring system.

wife3_enabled(true)   -- Enable (default)
wife3_enabled(false)  -- Disable

wife3_setJudgePreset(judgeNum: Int)

Set difficulty preset (1-9). See Judge Presets for details.

wife3_setJudgePreset(4)  -- J4 = Standard difficulty
wife3_setJudgePreset(9)  -- J9 = JUSTICE (hardest)

wife3_setJudgeScale(scale: Float)

Manually set judge scale value (advanced users).

wife3_setJudgeScale(1.0)   -- Same as J4
wife3_setJudgeScale(0.4)   -- Same as J9

Note: Scale range is 0.009 to 0.090. Values outside this range are clamped.

wife3_setShowTimingDisplay(show: Bool)

Show/hide color-coded timing feedback display (shows hit accuracy in milliseconds).

wife3_setShowTimingDisplay(true)   -- Show timing (default)
wife3_setShowTimingDisplay(false)  -- Hide timing

wife3_setReplaceScoreText(replace: Bool)

Enable/disable replacing Psych Engine's default score text.

wife3_setReplaceScoreText(true)   -- Replace score text (default)
wife3_setReplaceScoreText(false)  -- Keep Psych Engine score, calculate Wife3 in background. Useful for custom HUDs that doesn't use the scoreTxt object.

wife3_setKadeEngineStyle(kadeStyle: Bool)

Switch between Kade Engine style and Wife3/Psych Engine style score text formats.

wife3_setKadeEngineStyle(false)  -- Psych Engine style (default)
wife3_setKadeEngineStyle(true)   -- Kade Engine style

Formats:

  • Psych Engine Style: Score: 0 | Misses: 0 | Rating: AAA (98.45%) - MFC
  • Kade Engine Style: Score: 0 | Combo Breaks: 0 | Accuracy: 98.45 % | (MFC) AAA

wife3_setUseEtternaFCTiers(useEtterna: Bool)

Choose between Etterna and Psych Engine FC tier naming conventions.

wife3_setUseEtternaFCTiers(false)  -- Psych Engine style: SFC (default)
wife3_setUseEtternaFCTiers(true)   -- Etterna style: PFC

Tier Names:

  • Etterna: MFC, PFC, GFC, FC, SDCB, Clear
  • Psych Engine: MFC, SFC, GFC, FC, SDCB, Clear

wife3_resetAccuracy()

Reset all Wife3 counters to zero.

wife3_resetAccuracy()

Data Getter Functions

wife3_getPercent(): Float

Returns current accuracy percentage (0-100) based on notes hit/missed so far.

local accuracy = wife3_getPercent()
-- Example: 98.45

wife3_getTotalPercent(): Float

Returns total chart accuracy percentage if all remaining notes are hit perfectly.

local totalAccuracy = wife3_getTotalPercent()
-- Example: 99.12

wife3_getScore(): Int

Returns current song score (Wife3 calculated).

local score = wife3_getScore()
-- Example: 987654

wife3_getGrade(percent: Float): String

Returns letter grade for a given accuracy percentage.

local currentAccuracy = wife3_getAccuracy()
local grade = wife3_getGrade(currentAccuracy)
-- Returns: 'AAAAA', 'AAAA', 'AAA', 'AA', 'A', 'B', 'C', 'D', or 'F'

wife3_getJudgeScale(): Float

Returns the current judge scale value.

local scale = wife3_getJudgeScale()
-- Example: 1.0 (J4), 0.4 (J9)

wife3_getJudgePreset(): Float

Returns the current judge preset number (1-9), including interpolated values for custom scales.

local preset = wife3_getJudgePreset()
-- Example: 4.0 (J4), 9.0 (J9), 4.5 (between J4 and J5)

wife3_getReplaceScoreText(): Bool

Returns whether Wife3 score text replacement is enabled.

local isReplacing = wife3_getReplaceScoreText()

wife3_getKadeEngineStyle(): Bool

Returns whether Kade Engine style formatting is enabled.

local isKadeStyle = wife3_getKadeEngineStyle()

wife3_getUseEtternaFCTiers(): Bool

Returns whether Etterna FC tier naming is enabled.

local isEtternaStyle = wife3_getUseEtternaFCTiers()

wife3_getShowTimingDisplay(): Bool

Returns whether timing display is enabled.

local isTimingVisible = wife3_getShowTimingDisplay()

Advanced Data Access

wife3_getCurrentAccuracy(): Float

Returns raw Wife3 points accumulated from notes hit.

local currentPoints = wife3_getCurrentAccuracy()
-- Example: 345.67

wife3_getMaxAccuracy(): Float

Returns maximum Wife3 points earned so far (current performance ceiling).

local maxPoints = wife3_getMaxAccuracy()
-- Example: 350.00

wife3_getTotalAccuracy(): Float

Returns total possible Wife3 points for the entire chart.

local totalPoints = wife3_getTotalAccuracy()
-- Example: 500.00

wife3_getSongScore(): Int

Direct access to song score (same as wife3_getScore()).

local score = wife3_getSongScore()

Judgement Counter Functions

While Wife3 doesn't fully rely on Judgement windows, it still trackS five types of judgements. These counters are useful for detailed accuracy analysis.

wife3_getMarvelousHits(): Int

Returns the number of marvelous hits (≤ 22ms * judge scale).

local marvelous = wife3_getMarvelousHits()
-- Example: 245

wife3_getPerfectHits(): Int

Returns the number of perfect hits (≤ 45ms * judge scale).

local perfect = wife3_getPerfectHits()
-- Example: 12

wife3_getGreatHits(): Int

Returns the number of great hits (≤ 90ms * judge scale).

local great = wife3_getGreatHits()
-- Example: 3

wife3_getGoodHits(): Int

Returns the number of good hits (≤ 135ms * judge scale).

local good = wife3_getGoodHits()
-- Example: 1

wife3_getBadHits(): Int

Returns the number of bad hits (≤ 180ms * judge scale).

local bad = wife3_getBadHits()
-- Example: 0

Timing Windows

Timing windows scale with the judge preset. At J4 (scale 1.0):

Judgement Timing Window Description
Marvelous ≤ 22ms Perfect timing
Perfect ≤ 45ms Excellent timing
Great ≤ 90ms Good timing
Good ≤ 135ms Acceptable timing
Bad ≤ 180ms Poor timing

Example: At J9 (scale 0.4), timing windows are 40% tighter:

  • Marvelous: ≤ 8.8ms
  • Perfect: ≤ 18ms
  • Great: ≤ 36ms
  • Good: ≤ 54ms
  • Bad: ≤ 72ms

wife3_getTimingWindow(windowType: String): Float

Returns the timing window in milliseconds for a specific judgement type.

local marvelousWindow = wife3_getTimingWindow('marvelous')
-- Returns: 22.0 (at J4)

local perfectWindow = wife3_getTimingWindow('perfect')
-- Returns: 45.0 (at J4)

Valid window types: 'marvelous', 'perfect', 'great', 'good', 'bad'

FC Tier System

wife3_getRatingFC(): String

Returns the current FC tier based on performance.

local fcTier = wife3_getRatingFC()
-- Returns: 'MFC', 'PFC'/'SFC', 'GFC', 'FC', 'SDCB', or 'Clear'

FC Tier Breakdown

Tier Requirements Description
MFC All Marvelous (no Perfect or worse) Marvelous Full Combo
PFC/SFC No Great or worse (Perfect and Marvelous only) Perfect/Sick Full Combo
GFC No Good or worse (Great, Perfect, Marvelous) Great Full Combo
FC No Bad or worse (Good, Great, Perfect, Marvelous) Full Combo
SDCB 1-9 misses Single Digit Combo Break
Clear 10+ misses Song cleared

FC Tier Naming Conventions

Two naming styles are supported:

Etterna Style (Second tier: PFC)

  • Matches Etterna's terminology
  • Perfect = Second best judgement

Psych Engine Style (Second tier: SFC)

  • Matches Psych Engine's terminology
  • Sick = Second best judgement

Toggle between styles:

wife3_setUseEtternaFCTiers(true)   -- Use PFC
wife3_setUseEtternaFCTiers(false)  -- Use SFC (default)

Utility Functions

wife3_formatPercent(value: Float): String

Format a number to 2 decimal places.

local formatted = wife3_formatPercent(98.456789)
-- Returns: '98.46'

wife3_updateScoreText()

Manually update the score text display. Called automatically after hits/misses.

wife3_updateScoreText()

Score Text Formats

Wife3 supports two score text formatting styles that can be toggled dynamically.

Psych Engine Style (Default)

wife3_setKadeEngineStyle(false)

Format:

Score: 987654 | Misses: 5 | Rating: AAA (98.45%) - MFC

Components:

  • Score: - Current song score
  • Misses: - Total misses count
  • Rating: - Letter grade with percentage in parentheses
  • FC tier after dash

Kade Engine Style

wife3_setKadeEngineStyle(true)

Format:

Score: 987654 | Combo Breaks: 5 | Accuracy: 98.45 % | (MFC) AAA

Components:

  • Score: - Current song score
  • Combo Breaks: - Total misses count
  • Accuracy: - Percentage with space before %
  • FC tier in parentheses followed by grade

Initial State Display

Before any notes are hit:

Psych Engine Style:

Score: 0 | Misses: 0 | Rating: ?

Kade Engine Style:

Score: 0 | Combo Breaks: 0 | Accuracy: ?

Background Calculation Mode

You can disable score text replacement to run Wife3 calculations in the background:

wife3_setReplaceScoreText(false)

This keeps Psych Engine's default score text while allowing you to access Wife3 data through getter functions for custom UIs

Judge Presets

Judge presets control the timing window difficulty. Lower numbers are easier (wider timing windows), higher numbers are harder (tighter timing windows).

Preset Judge Scale Value Description Typical Use Case
1 J1 4.0 Easiest Casual play, story mode
2 J2 3.0 Very Easy Beginner friendly
3 J3 2.0 Easy Learning new charts
4 J4 1.0 Standard Default/Competitive baseline
5 J5 0.9 Slightly Hard Intermediate challenge
6 J6 0.75 Hard Advanced players
7 J7 0.6 Very Hard Expert challenge
8 J8 0.5 Extremely Hard Mastery testing
9 J9 0.4 JUSTICE Hardest possible

Setting Judge Preset

wife3_setJudgePreset(4)  -- Standard (default)
wife3_setJudgePreset(9)  -- JUSTICE (hardest)

Manual Scale Setting

For fine-tuned control, use wife3_setJudgeScale():

wife3_setJudgeScale(1.0)   -- J4 equivalent
wife3_setJudgeScale(0.6)   -- J7 equivalent
wife3_setJudgeScale(0.85)  -- Custom (between J5 and J6, so basically J5.5)

Grading System

Wife3 uses a letter grade system based on accuracy percentage:

Grade Min % Description Tier
AAAAA 99.70% Quadstar Nearly perfect
AAAA 99.50% Quad Exceptional
AAA 99.00% Triple Excellent
AA 98.00% Double Very Good
A 96.50% Single Good
B 93.00% B Tier Above Average
C 90.00% C Tier Average
D 80.00% D Tier Below Average
F < 80.00% Failed Needs Improvement

Grade Calculation

Grades are calculated in real-time based on current accuracy:

local currentAccuracy = wife3_getAccuracy()
local currentGrade = wife3_getGrade(currentAccuracy)
-- Returns current grade based on accuracy

local hypotheticalGrade = wife3_getGrade(97.5)
-- Calculate grade for any percentage

Clone this wiki locally