Calculated Odds: Hit Chance and Damage Preview Kit
README.md
Calculated Odds (forecastKit): hit chance and damage preview for turn-based tactics
forecastKit gives a tactics game the "72% to hit · 3-5 damage" moment every XCOM-style or Fire Emblem-style game lives on: the odds math (cover, range falloff, flanking, high ground, armor, crits, grazes, kill chance), an on-screen preview in 4 styles × 5 themes, a result popup in 4 result styles, and a seeded resolve that is guaranteed to land inside what the preview showed and to come out the same on every machine.
forecastKit.odds: pure, deterministic math.Odds.compute(spec)returns a preview,Odds.resolve(preview, seed)a result.forecastKit.preview: the on-screen preview (big,duel,tooltip,minimalinclean,scifi,fantasy,pixel,cartoon), anchored over the target, plus the self-clearing result in thestamp,burst,tickerorbannerstyle (HIT / CRIT / GRAZE / MISS / HEAL).OddsPreviewcomponent: set the look for a scene with one field each (style,theme,resultStyle), and keep anchored previews following the target every frame.forecastKit.resultStyles,forecastKit.themes,forecastKit.pixelFont: the result builders, the theme tokens and the 5×7 bitmap type the pixel theme draws with.- Guide: how-to-show-hit-chance-and-damage-before-an-attack (math, grazes, styles, and keeping the result honest in multiplayer).
- Test suite
forecastKit_odds(11 tests, including 10,000-seed "resolve stays inside the preview" with grazes, and every result style rendering every outcome in every theme).
No dependencies.
Install
zero zeromind installAsset <forecastKit package guid>
(or search ZeroMind for "Calculated Odds" / "hit chance preview"). Everything lands in /source/forecastKit.package.
30-second example
local Odds = require("forecastKit.odds")
local Preview = require("forecastKit.preview")
-- 1. Work out the odds when the player hovers a target.
local p = Odds.compute({
aim = 75, cover = "half", distance = 9, optimalRange = 6,
damage = { min = 3, max = 5 }, armor = 1, critChance = 10, targetHp = 8,
})
-- p.hitChance == 40, p.damage == {min=2,max=4}, p.grazeChance == 15, p.grazeDamage == {min=1,max=2}
-- p.breakdown = {Base aim 75, Half cover -20, Range -15}
-- 2. Show it over the target (an entity, a vector or {x,y,z}).
Preview.setStyle("big") -- or "duel", "tooltip", "minimal"
Preview.setTheme("scifi") -- or "clean", "fantasy", "pixel", "cartoon"
Preview.setResultStyle("burst") -- or "stamp" (default), "ticker", "banner"
Preview.show(p, { anchor = targetEntity, lift = 2.4, title = "Rifle Shot",
attacker = { name = "Vasquez", hp = 9, maxHp = 12 },
target = { name = "Raider", hp = 8, maxHp = 10 } })
-- 3. On confirm: resolve with a seed every peer shares, and show the outcome.
local result = Odds.resolve(p, Odds.seed(matchId, turn, attackerId, targetId))
-- result.outcome is "hit", "crit", "graze", "miss" or "heal"
Preview.showResult(result) -- plays and clears by itself
No code for the look at all: add the OddsPreview component to any entity and set style / theme / resultStyle.
API
forecastKit.odds (pure, deterministic)
Odds.compute(spec) -> preview
| spec field | default | meaning |
|---|---|---|
aim | 75 | attacker base accuracy (0-100) |
defense | 0 | target evasion, subtracted |
cover | none | "none"/"half"/"full" or 0/1/2; penalties half -20, full -40 |
coverPenalty | { half =, full = } override | |
distance, optimalRange | enable range; falloff (5) hit% lost per cell beyond optimal, closeBonus (0) per cell inside | |
flanked | false | cancels cover (listed as "Flanked"), flankCritBonus (+10) crit |
height | 0 | levels above (+) / below (-) the target; heightBonus (10) per level |
modifiers | { {label, value} } extra hit modifiers | |
damage | required | { min, max } |
armor | 0 | flat reduction per roll, floor 1 (0 if damage.max == 0) |
critChance, critBonus, critMultiplier | 0, none, 1.5 | crit chance of a hit; multiplier rounds down |
graze | 15 | graze band width in percentage points just above the hit chance; 0 turns grazes off |
grazeMultiplier | 0.5 | share of the after-armor damage a graze deals (rounded down, at least 1) |
targetHp | enables killChance | |
guaranteed | false | 100% hit (melee abilities) |
minChance, maxChance | 5, 95 | clamp (guaranteed/heal override to 100) |
heal | false | heal preview: 100%, damage = heal amount, no crit, no graze, no armor |
preview = { hitChance, critChance, grazeChance, damage {min,max}, critDamage {min,max}, grazeDamage {min,max}, breakdown {label,value}[], critBreakdown {label,value}[], rawChance, clamped, killChance?, killChanceOnHit?, expectedDamage, heal, guaranteed, spec }
- Grazes: a roll that misses by a little clips the target.
grazeChanceismin(graze, 100 - hitChance), so the hit, graze and miss chances always add up to 100.grazeDamageis half the normal damage range (rounded down, at least 1). A heal, a guaranteed hit at 100%, or a weapon that deals 0 never grazes. killChanceis the chance this attack kills (hits and grazes, exact over the integer damage roll and crits);killChanceOnHitis the same given a clean hit. A possible kill never shows 0, an uncertain one never 100.breakdownlists every modifier that moved the hit chance;rawChance/clampedtell you when min/max clamped it.
Odds.resolve(preview, seed) -> { hit, crit, graze, outcome, damage, roll (1..100), critRoll, kills?, heal }
hitiffroll <= hitChance; damage insidepreview.damage(orcritDamageon a crit).grazeiffhitChance < roll <= hitChance + grazeChance; damage insidepreview.grazeDamage, never a crit.- Otherwise a miss: 0 damage.
outcomeis"hit","crit","graze","miss"or"heal". - Integer hash RNG, identical on every machine; the draw order is unchanged from 1.0.1, so the same seed gives the same roll as before.
Odds.seed(...): stable FNV-1a hash of any numbers/strings. Odds.rng(seed): next(min, max) deterministic integer stream. Odds.summary(preview): "72% · 3-5". Odds.VERSION = "1.0.2".
forecastKit.preview
| call | does |
|---|---|
Preview.STYLES, Preview.THEMES, Preview.RESULT_STYLES | the ids below |
Preview.setStyle(name), Preview.setTheme(name), Preview.setResultStyle(name) | the global default: the one-change switch |
Preview.style(), Preview.theme(), Preview.resultStyle() | current defaults |
Preview.show(preview, opts) | opts = { anchor, lift?, attacker = {name,hp,maxHp,side?,color?}, target = {...}, title?, style?, theme?, avoid? }; avoid is a list of screen boxes { x, y, w, h } (UI points, e.g. from ui.getLayoutInfo(id)) that the duel card must not cover: it takes the free spot nearest bottom centre (above, below, left or right of them) |
Preview.hide() | hide it |
Preview.showResult(result, opts?) | the outcome at the anchor in the result style, 1.2 to 1.7 s, then gone; hides the card while it plays unless opts.keepPreview; opts.resultStyle overrides the style, opts.preview supplies the chances when no preview is shown |
Preview.update(dt?) | re-project the anchor (an internal loop and OddsPreview already call it) |
Preview.catalog() | `{ kind = "style" |
Preview.isShown() | true while shown |
anchor accepts an entity, a vector, {x,y,z}, {x=,y=,z=} or a function returning one; lift raises it in world units (put the preview over the head). Screens: forecastKit.preview and forecastKit.preview.result (layers 60/61, transparent: they never take clicks). Sizes scale with ui.screenSize(), so phones get a compact layout.
Preview styles
Every style shows the graze chance (and graze damage where there is room) next to hit, damage and crit.
| id | looks like |
|---|---|
big | a huge hit % on a compact plate over the target, damage / crit chips, a graze line and a pulsing KILL badge |
duel | bottom card: attacker vs target, HP bars with the certain (pulsing) and possible (striped) damage chunk, hit %, crit %, damage, graze, kill chance, full breakdown |
tooltip | small card beside the target: hit, damage, crit (with crit damage), graze (with graze damage), kill, breakdown |
minimal | one pill: 72% · 3-5 +15% graze |
Result styles
Each covers HIT, CRIT, GRAZE, MISS and HEAL (with a KO mark on a kill) in all five themes.
| id | looks like |
|---|---|
stamp (default) | the outcome word and damage stamped over the target ("HIT 4", "GRAZE 2"): pops, shakes on a crit, floats up and fades |
burst | a huge damage number punched in over a spinning starburst in the outcome colour, the outcome word above it; a miss puffs out as an empty ring |
ticker | a compact themed line sliding out beside the target: outcome, damage and the roll against the chance; quick results stack |
banner | a full-width band sweeping across the screen: the outcome word large, the damage, and the roll against the hit and crit chance |
Themes
| id | look |
|---|---|
clean | neutral modern glass, soft shadows, rounded |
scifi | cyan hologram, notched corners, brackets, scanlines, glowing monospace |
fantasy | parchment, gold leaf border and corner studs, serif ink lettering |
pixel | hard edges, chunky white borders and bevels, 5×7 bitmap type, stepped colours |
cartoon | thick black outlines, candy colours, stroked heavy numbers, bouncy pop-in |
Demo
The world this package comes from has a gallery scene: keys 1-4 style, 5-9 theme, R result style, Q scenario (cover shot, flank, long snipe, heal), Space resolve, or the on-screen buttons on touch.
Versions
- 1.0.4:
opts.avoidplacement searches the spots around every box (above, below, left, right) and takes the free one nearest bottom centre, so the duel card also fits between panels at different heights (a unit card bottom-left and a list top-right). - 1.0.3:
Preview.showtakesopts.avoid, the screen boxes of the game's own panels (unit card, buttons, lists); the bottom-dockedduelcard rises above any of them it would cover, so it never sits on a game's HUD at any screen size. - 1.0.2: renamed from
oddsKitto forecastKit ("Calculated Odds"); the package keeps the same asset guid. Requires change fromoddsKit.odds/oddsKit.previewtoforecastKit.odds/forecastKit.preview, the component isforecastKit.OddsPreview, the screens areforecastKit.preview/forecastKit.preview.result, and the test suite isforecastKit_odds. NooddsKitaliases are kept. Adds the graze outcome (spec.graze,spec.grazeMultiplier,preview.grazeChance,preview.grazeDamage,result.graze,result.outcome), shown on every preview style. Grazes are on by default (15 points): passgraze = 0to keep 1.0.1 behaviour. Adds four result styles (stamp,burst,ticker,banner) withPreview.setResultStyleand theresultStylefield onOddsPreview. - 1.0.1: first public release as oddsKit.