Full Guide

01

Where your settings live

Everything is stored client-side, in your Minecraft config folder. Nothing is sent anywhere and no server ever sees it.

simplecps.json

The live config — one flat file holding every setting for every module.

simplecps_stats.json

Your best combo, stored as {"bestCombo": N}. It is kept apart from the config, so presets, server configs and share codes never carry it, and only Reset Best clears it.

simplecps_presets/

Your named presets, one .json per preset. The file name is the name you see in-game.

simplecps_server_presets/

Per-server configs, one .json per server. The file name is the server address.

_labels.json

Inside the server folder — the friendly names you gave your servers. Not a server itself.

Fields you may see but that do nothing

If you open simplecps.json in a text editor you will find a few keys the current build never reads. They are kept because a field name is a key on disk — deleting them from the mod would silently drop settings out of everyone's existing file.

keystrokesEffectMode

Read once when an old config is loaded, to work out which animations you had. Never written back.

keystrokesMotion
keystrokesFill

The single-animation predecessors of the current lists. Same story — migration only.

comboHeatmap
comboRainbow

The two switches Color Mode replaced. Read once, the first time an old config is loaded, to work out which Color Mode you had.

comboText

The old combo suffix. Read once, the first time an old config is loaded, to turn it into your Format: a suffix of X becomes {combo} X.

showLCTRL
showLSHIFT
showSpace

Left over from before the layout was freely editable. Nothing reads them; add or remove those keys in the designer instead.

comboResetOnAnyDamage is not one of them: it is Break on Any Damage, which kept its key when it was renamed.

02

The four surfaces

There are four places settings can be changed, and several settings live on exactly one of them. This is the table to check when you cannot find something.

In-world HUD editor

Press Right Shift in-game. Rebindable under Controls, in a category called Eymistaken's HUD. It only opens when no other screen is up.

Settings screen

From the editor's Settings… row, or from Mod Menu.

Keystrokes Designer

Keystrokes page → Layout → Open Designer, or right-click the Keystrokes module in the editor.

Mod Menu

Optional. When it is not installed, the settings screen is still reachable through the editor.

Settings that exist in only one place

03

Placement and the layout engine

Every module gets the same four placement rows, on its Position tab. Third-party modules get them too.

The anchor grid is 3×3 but only five cells do anything: the four corners and the center. The four edge cells are inert.

Auto-stacking versus manual placement

Modules that share a corner are stacked along that edge automatically, so they never sit on top of each other. A module leaves auto-stacking the moment you give it a non-zero offset or drag it in the editor; from then on it is placed exactly where you put it, clamped to the screen, and the stack closes up behind it.

Centered modules are centered rather than stacked, so two of them can overlap unless you offset one.

Prevent Overlap

On by default. Pushes colliding modules to the nearest free spot so two of them never cover the same pixels. General → Editor.

04

The HUD editor

Press Right Shift in-game. The editor draws over your live HUD, so what you are dragging is the real thing at its real size.

Mouse and keyboard

Left-click + drag

Move a module — or a single armor slot once you have ungrouped them. Snaps to other modules' edges and centers, then to the grid if the grid is on.

Hold Shift while dragging

Turns snapping off for that drag. Free placement, pixel for pixel.

Scroll wheel

Scale the module under the cursor by 5% per notch, from 50% to 300%. This saves immediately — there is no drag to release.

Drag on empty space

Marquee select. Everything inside the box is selected.

Arrow keys

Nudge the selection one pixel.

Right-click a module

Its own context menu.

Right-click empty space

The global menu.

Align and distribute

Select two or more elements and a toolbar appears at the top of the screen.

L CX R

Align left, match center on X, align right.

T CY B

Align top, match center on Y, align bottom.

DX DY

Distribute horizontally or vertically — equal gaps between elements. Needs three or more.

The global menu

Right-click anywhere empty. Nine rows:

Settings…

Opens the full settings screen.

Prevent Overlap

Toggles collision handling for the whole HUD.

Grid

Left-click toggles the grid. Right-click cycles its size through 4, 8, 16 and 32 pixels.

Save Config

Saves everything as a preset called Config 1, Config 2, and so on — the first free number.

Configs

Hover for your saved presets. Left-click a name to load it, the bin icon to delete it, right-click to rename it.

Server Configs

Hover for your per-server configs. The title row switches the whole feature on and off.

Export Code

Copies your whole HUD to the clipboard as a share code. The row reads Copied! for a moment.

Import Code

Opens a text box you can paste into with Ctrl+V. Your current config is backed up to a preset first.

Reset HUD

Sends every module back to its default anchor, offset and scale. Colors and behavior are left alone.

05

The settings screen

One page per module in a sidebar, then a General page, then a Plugins divider with a page for each third-party module you have installed. Every module page has an enable toggle in its header; General is global and cannot be switched off.

What is on the screen

Search settings

Filters every row on every page into a single results page. Faster than remembering which tab a setting is on.

Preview

A live render of whichever module you are looking at, updating as you change things. On the Combo page it plays a looping demo fight, so the sliders, the line, the colors and the style can be tried without landing a hit — see the Combo preview.

Info

The description of the row you last touched, plus its default value and a button to put it back.

Presets

Your saved configs. Click one to load it, or Save Current to add one.

Share code

A field with Export and Import. Import falls back to your clipboard if the field is empty.

The three buttons that ask twice

Reset All Settings

Every module returns to its default position, color and scale. Saved presets and plugin module data are kept. Cannot be undone.

Cancel

Puts back everything changed since the screen opened — including edits already written to disk.

Done

Closes the screen. Changes were already saved as you made them; the footer shows the config path.

06

CPS

Clicks per second for the left and right mouse buttons, counted over a rolling one-second window. It is the only module that is on by default.

In the editor's right-click menu: Reset Settings, Enable CPS, Text Color, Scale %.

07

Ping

Your latency to the current server, in milliseconds. Off by default.

In the editor's right-click menu: Reset Settings, Enable Ping, Scale %, Text Color.

08

FPS

Frames per second. Off by default.

In the editor's right-click menu: Reset Settings, Enable FPS, Text Color.

09

Combo

Counts consecutive hits. Off by default. A hit counts once the server confirms it landed — unless you set Hit Detection to Client — and a combo someone lands on you is counted too, shown as a negative number on a line of its own. This is the module with the most behavior to tune, because "what counts as a combo" genuinely differs between servers.

Behavior

Style

Heatmap tiers

Animation

Background

What counts as a hit

Hit Detection decides when a hit is counted, Combat Mode whether it was strong enough to count, and Only Players what it has to land on.

Server

The default. Attacking only records a pending hit, which counts when the server sends the damage event for that target. The mod waits roughly 200 ms plus your ping for it, and never longer than a second. The server sends that event only for a fresh hit that actually landed, so hits into the target's invulnerability frames, hits blocked by a shield, arrows and sweep damage do not add to the combo.

Client

The old behavior: every attack you send counts.

Combat Mode

Applies under either detection mode. Modern counts only full-strength hits, made with the attack cooldown at least 90% recharged, and Classic counts every hit. Under Modern, spam-clicking right after a full-strength hit does not turn that hit into a weak one while the server is about to confirm it.

Only Players

On by default, so only hits on players count. Turned off, hits on mobs count too, and so do mobs that land a combo on you.

When a combo ends

Timeout

No counted hit for as long as the Timeout, and the combo ends — or starts draining, if Decay is on.

Distance

A target more than 20 blocks away counts as a timeout. This check always applies.

Target switch

With Continue On Target Switch off, hitting a different target ends the combo and starts a new one.

Finisher

A target that dies within a second of your last hit on it plays the finisher moment — see How hits land. With Continue On Target Switch off the combo ends there; with it on, the combo carries on.

Damage

With Break on Any Damage on, any damage you take breaks the combo, falls and lava included. Turned off, only damage from someone you are fighting does: anything you have landed a counted hit on within the Timeout. Thorns never breaks it.

World change

Changing world or dimension resets the tracking.

Decay is a setting of its own, and the distance check applies whether it is on or not. With Decay on, a combo that breaks or times out drains one hit per second instead of ending. A counted hit stops the drain, and the combo carries on from the count it had reached. An old config that had Break on Any Damage off arrives with Decay switched on.

Min Display, 2 by default, is the smallest count shown at all, both for your combo and for one landed on you. Always Show — Hide When Inactive turned off — keeps your own line on screen regardless.

A combo that ends on a timeout, the distance check or a finisher, at a count of at least Min Display, lingers with its final count for 1.2 seconds: full brightness for the first 0.3 seconds, then down to 45% opacity over the next 0.25. After that it disappears if Hide When Inactive is on, or drops back to 0 if it is off. A new combo, yours or one landed on you, takes over right away.

A combo landed on you

Hits the same attacker lands on you in a row are counted as well, and shown as a negative number: {combo} in your Format is written with a minus sign, so the default reads -5 Combo.

What counts

Hits from players, and from mobs too if Only Players is off. Melee and projectile hits both count, arrows included. Thorns and environmental damage with no attacker do not.

New attacker

A hit from a different attacker starts the count again from 1.

When it ends

When you land a counted hit on that attacker, when the attacker dies, or when the Timeout passes after their last hit.

If you have a combo of your own at the same time, the two stack: yours on top, a short 1 px divider 60% as long as the wider line, and the negative line underneath. With no combo of your own, the negative line takes the main line's place. Stacking only happens with Decay on or Break on Any Damage off; otherwise the first hit you take has already ended your combo. For as long as a negative line can appear, its space is reserved up front, so modules on the same edge do not jump every time you are hit.

Its color deepens with the count, blending smoothly from yellow to orange at tier 1 and red at tier 2, then through dark red to nearly black at tier 3 and beyond. As the text darkens its edge turns a dim red, so a black number never disappears. These colors ignore Color Mode. The line shakes harder as its count grows, up to its strongest at tier 3, and every hit you take gives it a short jolt.

How hits land

Every counted hit punches the number up and lets it settle back with a slight bounce. On the big moments the counter also freezes for an instant, like hitstop in a fighting game: the punch, the shake on both lines, the negative line's color blend and the divider all stop together, then carry on from where they were. No freeze ever lasts longer than 160 ms. The figures below are at Impact 100%.

Your own count starts to shake at tier 3, by 1 px. Past tier 3 the shake builds to 3 px over as many hits as separate tier 2 from tier 3 — four on Medium — at Shake 100%. Freezes hold the shake too, and a combo that has ended does not shake.

The Animation tab, between Style and Background, tunes these separately, because a single intensity setting could not, say, keep the freezes and turn the shake off.

Impact %

The punch scales in direct proportion and freezes more gently: at 150% the punch is 1.5 times as big and a freeze about 1.3 times as long. At 0 there is no punch and no freeze, and a broken combo gives way without freezing. The gold BEST flash and its label show at any value.

Shake %

Your count's shake past tier 3, and the negative line's growing shake. At 0 both stay still, whatever the heatmap settings.

Hit Jolt %

The negative line's jolt on each hit you take: 1.5 px at 100%, fading out over 300 ms. It is independent of Shake.

Your best combo

Your best combo is kept between sessions, in simplecps_stats.json beside simplecps.json in your Minecraft config folder, as {"bestCombo": N}. It is written when a combo ends, or as the game closes if you quit mid-combo. With an empty or corrupt file, the record starts from 0.

The record is not part of the config. Presets, server configs and share codes do not carry it, and neither Reset Settings nor Reset All Settings clears it.

A new best plays once per combo, when the combo passes the record as it stood when the combo began and reaches at least tier 2. The number lands a little harder, turns gold (#FFB800) for the freeze, and fades back to its own color over 0.4 seconds. A small gold BEST label appears beside it: half the number's size, level with its top, on the side away from the anchor — to the right on a left or center anchor, to the left on a right anchor. The label stays for 1.6 seconds and fades out over the last 0.3. It grows, shakes and freezes with the number, and never changes the module's size.

A short combo that beats a low record is not announced until it reaches tier 2. On a fresh install the record is 0, so the first combo to reach tier 2 gets announced.

Reset Best, on the Behavior tab, forgets the record. It asks first, in a Reset Best Combo window that shows your current best. The settings screen's Cancel cannot bring it back, since the record is not part of the config.

The line under the count

While your line is on its own, Line draws a 1 px line under the count.

Timeout

The default. A bar in the count's color at 75% opacity that shortens with the time the combo has left and refills on every counted hit. It is hidden while a combo drains with Decay, lingers at its end or breaks. It shows the real timeout, so it keeps moving through freezes.

Hits

Your last 8 counted hits, one segment each: gray for a normal hit, white for a sprint hit, gold for a critical one. A critical is confirmed by the server's critical-hit notification, and a critical that kills still shows gold. A new segment flashes white for a moment. The newest sits at the right end, and with fewer than 8 hits the segments gather on the anchor side. The strip fades while a combo drains with Decay, and through a combo's end it stays up with that combo's hits.

Both

The timeout bar on top, and the hit strip 1 px below it.

Off

No line.

When a negative line stacks under yours, the line turns into the short divider between them: the bar shortens and takes on the divider's color, and the strip fades out. It comes back when the negative line goes. The divider shows even with Line set to Off.

Heatmap colors and custom tiers

Color Mode takes the place of the separate heatmap and rainbow switches, which could both be on at once, with the heatmap quietly winning. One setting with three values leaves nothing to conflict.

Static

Your count stays in the Text Color.

Rainbow

Your count cycles through every hue. Text Color is not used.

Heatmap

Text Color up to tier 1. From tier 1 to tier 2 it blends from Text Color to Heatmap Mid Color, from tier 2 to tier 3 on to Heatmap Top Color, and from tier 3 on it stays Top Color. The defaults, #FF0000 and #550000, take it from the text color to red and then to dark red — no blue, and no black.

As the count darkens its edge warms to a dim red, so it stays readable even if you pick black. An old config loads as Heatmap if its heatmap switch was on, as Rainbow if only its rainbow switch was, and as Static if neither was.

Heatmap Difficulty sets the tiers — see the tier table above — and they decide more than color: where your count starts to shake (tier 3), where a new best can flash (tier 2), and the steps in a negative line's color and shake. That holds even when Color Mode is not Heatmap. Changing the difficulty resets a running combo, and so does changing a custom tier while Custom is selected.

Custom Tier 1, 2 and 3 always stay in order, each at least 1 above the one before it. Changing one moves the others out of its way: raising Tier 1 past Tier 2 pushes Tier 2 up, and Tier 3 as well if it has to; lowering Tier 3 pulls the others down.

Format and Style

Format replaces the old suffix: rather than text after the number, you write the whole readout, up to 64 characters, with two placeholders. {combo} is the count, with a minus sign on a combo landed on you (-5), and {best} is your all-time best. Leave {combo} out and the count is added at the front with a space, so editing the format can never lose the number; an empty format shows the count alone. An old config keeps its look: a suffix of X becomes the format {combo} X.

Style sets how that readout is drawn. Text puts the count and the rest of the format on one line. Big draws the count twice as large, with the format minus {combo} under it at normal size: {combo} Combo becomes a big 12 over Combo, x{combo} a big 12 over x, and a format of only {combo} leaves nothing underneath. A negative line uses the same style.

In Big, the punch, the shake and the freezes apply to the big number alone, so the text under it stays still and readable. Color, the gold flash and fading cover that text too, and the BEST label sits beside the big number at normal text size.

There is no separate badge or minimal style: Show Background with a Line gives the badge look, and a format of x{combo} the minimal one.

The preview and the editor

On the Combo page, the settings screen's preview plays a looping demo fight. The count climbs through the tiers with half a second between hits, pauses briefly in the middle while the timeout bar drains, goes three hits past tier 3 and ends on a finisher, with sprint and critical hits along the way. A combo landed on you shows up too: under yours during the last hits when stacking is possible, after your combo ends when it is not. The sliders, colors, line and style can all be tried without joining a world.

The demo starts over whenever Heatmap Difficulty or a custom tier, Decay, Break on Any Damage or Timeout changes.

The Right Shift editor shows a still sample instead: 8 Combo on Medium, with -5 Combo under it when stacking is possible, and a sample line. Nothing moves in the editor.

In the editor's right-click menu: Reset Settings, Enable Combo, Always Show (the inverse of Hide When Inactive), Color Mode, Style, Text Color, Format.

10

Reach

The distance of your last landed hit, in blocks, to two decimal places. Off by default.

In the editor's right-click menu: Reset Settings, Enable Reach, Always Show, Text Color, No Hit Text.

11

Armor HUD

Your four armor pieces and your held items, with durability. Off by default, and the only module that starts in the bottom left rather than the top left.

Splitting the slots apart

Right-click the Armor HUD in the editor and choose Ungroup. The six pieces — Helmet, Chestplate, Leggings, Boots, Main Hand, Off Hand — become independently draggable, each with its own offset, so you can put your boots somewhere entirely different from your helmet.

Right-click any detached slot and choose Group to snap everything back into the stack and clear all twelve offsets at once.

In the editor's right-click menu: Reset Settings, Ungroup, Enable Armor, Scale %, Vertical, Show Background, Durability Text, Damage Flash, Show Main Hand, Show Off Hand.

12

Keystrokes — module settings

The key display. These are the settings that apply to the whole cluster; anything about an individual key lives in the Designer.

The layout holds up to 256 keys. In the editor's right-click menu: Enable Keystrokes, Design, Board, Open Designer — this module has no Reset Settings row.

16

Fonts, outline and menu scale

On the General page. These apply to every module at once.

HUD font

The font applies to HUD modules and to this mod's own screens — the editor, the settings screen and the Designer. It never touches chat, the vanilla menus or anything another mod draws.

Text outline

Off by default, which gives you Minecraft's usual drop shadow. Turning it on draws a thin black outline on every side instead — noticeably more readable over bright terrain and snow.

Menu scale

The settings screen already holds one physical size across every Minecraft GUI Scale. Menu Scale % (50 to 200, default 100) nudges that baseline if you want the menus larger or smaller than the mod's own idea of right.

17

Presets and server configs

Two ways to keep more than one HUD around. Presets are named by you and switched by hand; server configs name themselves and switch on their own.

Saved configs

A preset is a complete copy of your settings. Save Config in the editor, or Save Current in the settings screen, names it Config 1, Config 2 and so on, taking the first free number.

• Left-click a name to load it
• Right-click to rename it — a name already in use is refused rather than overwriting
• The bin icon deletes it

A preset is validated before anything is applied, so a corrupt or hand-edited file cannot leave you with a half-replaced config. Your best combo is not a setting and has a file of its own, so no preset carries it.

Server configs

On by default. There is nothing to press: while you are in a world, every save is mirrored into that server's own file, so "how my HUD looks here" is simply remembered. Join a server that already has one and it is applied silently.

• All your single-player worlds share one config
• mc.example.net and mc.example.net:25565 are treated as the same server
• Realms are keyed by their display name, since they have no usable address
• Your best combo is not in a server config either — it has a file of its own

Just before a silent switch, the config you are leaving is written to a preset called Auto Backup. It is a single rolling slot rather than a timestamp, because this fires on every join and timestamps would bury your Configs list within one session.

18

Share codes

Your whole HUD, packed into one line of text you can paste into Discord. Codes start with EYMHUD1-. Your best combo stays behind: it is not a setting, so no code carries it.

Two kinds of code

The two are not interchangeable, and giving one to the wrong screen is refused rather than half-applied: paste a keystrokes code into the settings screen and it tells you to use the Designer instead.

What a keystrokes code carries

The layout and the look: the design, the animations and their direction, the release trail, the board, the scale, the rainbow settings and all four colors — including anything a single key overrides on its own.

Limits and errors

A code is a string from a stranger, so every step of reading one is bounded: 64 KB of text at most, half a megabyte once unpacked, and a hard stop before anything larger is ever allocated. A malformed or oversized code is rejected outright — nothing is partly applied.

Not a valid share code

The text is malformed, too large, or was made by a newer version of the mod than you have.

No valid code in clipboard

You pressed Import with an empty field and nothing usable on the clipboard.

That's a keystrokes code

Right code, wrong screen — take it to the Designer.

That's a config code

The mirror image: take it to the HUD editor.

Imported from v1.2.0

It worked, but the code came from a different version of the mod. Worth a glance to check nothing looks off.

19

What each reset actually resets

Five buttons say some form of "reset" and none of them mean the same thing. This is the single most common source of surprise, so it gets its own table.

Third-party module settings survive a full reset on purpose — those modules provide their own Reset Settings row instead.

20

Gotchas

Things that look like bugs and are not.

Keystrokes has no background toggle

Set Background Opacity to 0. That is how the Frame, Bar and Segment designs get their transparent look.

Ping has no rainbow, Armor has no colors

Neither is an oversight. Armor draws items rather than text, so there is nothing to tint; the slot backgrounds are its equivalent switch.

Picking a design changed my colors

That is the design. A palette is what makes a style legible, so choosing one brings its own — along with its animations, and its arrangement if it has one. Export your layout before browsing the gallery if you want it back.

Changing heatmap difficulty dropped my combo

Expected — the tiers moved underneath it, so the count is reset rather than reinterpreted. Changing a custom tier while Custom is selected does the same.

A hit did not count

With Hit Detection on Server, a hit counts only once the server confirms it landed, so hits into a target's invulnerability frames or onto a shield, arrows and sweep damage never count. For the old count-every-attack behavior, set Hit Detection to Client.

A negative number appeared under my combo

That is a combo landed on you. It only stacks under yours with Decay on or Break on Any Damage off; otherwise the first hit you take ends your combo, and the negative line takes its place.

My custom tiers moved on their own

Each tier stays above the one before it, so changing one pushes the others out of its way.

BEST did not flash

It plays once per combo, and only once the combo that beats your record reaches tier 2.

The timeout bar keeps moving during a freeze

It shows the real time left, and a combo's timeout does not stop for freezes.

The timeout slider stops at 10 seconds

The slider covers 1 to 10, but the config itself accepts 0.1 to 60. A hand-edited file or an imported code can carry a value the slider cannot reach or display exactly.

Scaling in the editor saved without asking

Scroll-to-scale writes immediately, because there is no drag to release. Use undo in the Designer, or a preset, if you want a way back.

I cannot find the armor slot offsets

They exist only after Ungroup, and only in the in-world editor. Dragging is the interface — there are no rows for them.

I cannot find the animation checkboxes

They are in the Designer's Anim drawer, and nowhere else. Motions and fills are sets, and no other screen has a control that can express a set.

Every menu is unreadable

The Enchant font. Press Right Shift and use Restore Font in the bottom-right of the editor.