guessIo Game Guide
A complete, plain-language guide to how guessIo works: match rules, difficulty modes, progression, simulated players, accounts, and every screen in the app.
What Is guessIo?
guessIo is a real-time, competitive, multiplayer code-breaking game. It runs as a web app / installable Progressive Web App (PWA), working in a browser on phone or desktop.
The one-line pitch, taken from the app's own install listing:
"Analyse → Outsmart → Crack the Code."
A logic-deduction game where everyone races head-to-head to crack the same code.
A colored tile grid where every tile is a digit (0-9), never a letter.
Dark "hacker terminal" aesthetic, not playful or cartoonish.
How a Match Works: The Core Loop
The secret code
- Each round has one secret code, generated by the system: a string of unique digits (0-9, no repeats), a random length depending on the mode.
-
A leading zero is allowed: a code like
0473is valid. - One shared code per round. Every player at the table is trying to crack the same code; nobody is guessing an opponent's personal code. True in every mode, including 2-player, 3-player, 4-player, and solo Practice Mode.
Turn order
- Players take turns in a fixed rotation for that round.
- The rotation's starting player changes each round (round 2 starts with whoever was second in round 1, and so on), so no one player is stuck always going last.
Making a guess
On your turn, you enter a guess of the same length as the secret code, using unique digits (no repeats allowed in your guess either). After you submit, you get feedback on every digit you guessed:
| Feedback | Meaning | Standard-mode color |
|---|---|---|
| Correct | That digit is in the code, in the exact position you guessed | Green |
| Present | That digit is in the code, but in a different position | Yellow |
| Wrong | That digit is not in the code at all | Gray |
- This feedback is private: in online matches, only you see the color-coded result of your own guesses. Other players see what digits you guessed, not what the colors meant for you. Exception: local Pass & Play, where both people are on one screen anyway, so all feedback is visible to both.
- The guess limit is a shared budget for the whole round, not a per-player allowance. If it runs out before anyone cracks the code, the round is a draw; nobody scores it.
- The first player to guess the exact code wins that round.
Turn timer
- Each turn has a time limit; 15 seconds by default. If it expires, that player's turn is skipped (no guess submitted) and play passes to the next person.
- A disconnected player's turn is skipped immediately rather than waiting out the timer.
Winning the match: best of 3 rounds
A match is decided over up to 3 rounds:
- Round 1 alone never decides anything.
- After round 2: if one player is strictly ahead on rounds won, they win the match immediately.
- If there's a tie after round 2, for any reason (including 0-0, where both rounds were draws), the match always proceeds to a 3rd, deciding round. Whoever's ahead after round 3 wins; if still tied, the match ends in a draw.
Going idle
If a full rotation passes with nobody submitting a valid guess, everyone gets an on-screen warning. If that happens a second time in a row, the entire match (not just the round) is cancelled, and every player still in it is penalized: -30 rating (flat) and -10% of their current Points balance. This rule applies to Casual and Ranked matches alike.
Disconnecting & reconnecting
- If you lose connection, you get a 60-second grace window to reconnect before you're automatically counted as having forfeited.
- Reconnecting drops you right back into the match.
Quitting on purpose (Forfeit / Resign)
- A flag button is available throughout a live match. Using it asks for confirmation ("Leaving now counts as a forfeit... this may affect your rating") before it's applied.
- Logging out during a match also counts as a forfeit: the app warns you about this before logging you out.
- In a 2-player match, a forfeit ends the match immediately as a win for the other player. In a 3-4 player match, the match simply continues without the player who left.
Difficulty: Standard vs. Hardcore
Both modes are told the exact same underlying information about each guess. The difference is purely in how that information is displayed:
| Standard | Hardcore | |
|---|---|---|
| Right digit, right position | Shown as its own color (green) | Merged into the same color as "present" |
| Right digit, wrong position | Shown as its own color (yellow) | Merged into the same color as "correct": you just see "this digit is somewhere" |
| Digit not in the code | Gray | Gray (unchanged) |
In short: Standard tells you position; Hardcore only tells you presence/count. You still see how many of your digits belong somewhere in the code; you just work out which slot through further deduction. Because it's harder, a Hardcore win is worth more Points than a Standard win.
Player Counts & Round Sizes
Online matches support 2, 3, or 4 players. Code length and the shared guess budget scale with player count:
| Players | Code length | Guess budget per round |
|---|---|---|
| 2 | 4 digits | 10 guesses |
| 3 | 5 digits | 12 guesses |
| 4 | 6 digits | 15 guesses |
These same three number-pairs reappear in Practice/Guest Mode, just relabeled as a difficulty-style choice, since guest matches are always exactly 2 seats.
Ways to Play (Match Types)
There are three ways to start an online match, chosen from the "Select Match" screen:
| Type | Affects Rating? | Earns Points? | Saved to history/stats? | How you get matched |
|---|---|---|---|---|
| Casual | No | Yes | Yes | Matchmaking queue |
| Ranked | Yes | Yes | Yes | Matchmaking queue |
| Private Room | No | No | No: nothing is saved | Share a room code |
Casual & Ranked (matchmaking)
- You pick match type, difficulty, and player count, then join a queue for that exact combination.
- Matching is first-come-first-served, not based on skill or rating, even in Ranked. Whoever's next in the same queue bucket gets matched together.
- To keep matches starting quickly, empty seats are filled with simulated players: one added every 5 seconds (never all at once), while the system continues checking for real players in the meantime. This means a Ranked match can include simulated players alongside other opponents.
Private Rooms
-
The host picks a player count and difficulty and gets a
6-character room code
(letters and numbers, excluding the easily-confused
I,O,0,1). - Friends join by entering that code. Player count is locked once the room is created; only the host can start the match, and only once every seat is filled.
- Difficulty is also locked once the room is created, a read-only field for the life of the room, not something the host can change mid-lobby.
- Private matches are never written to the database at all: no match history entry, no statistics update, no points, no rating change for anyone, win or lose. The in-match Results screen still displays a rounds-won tally, but there's no "View Match Details" link afterward.
- If the host leaves before starting, host status passes to the next player in the room automatically.
Practice / Guest Mode (No Account Needed)
Anyone can play without creating an account, via a "Practice Mode" setup screen. Two local modes:
You against one of our models, entirely on your device.
Two people share one device, trading turns.
This runs the same rules engine as online play (same shared code per round, same best-of-3 structure, same Standard/Hardcore feedback rules) but simplified: no turn timers, no disconnect handling, and no idle-cycle cancellation, since there's no network connection involved.
Instead of a player count, you choose a Round Length, using the exact same numbers as the online table:
| Round Length | Code length | Guesses |
|---|---|---|
| Easy | 4 digits | 10 |
| Medium | 5 digits | 12 |
| Hard | 6 digits | 15 |
Key differences from online play
- Nothing is saved. The app repeats this warning at setup ("Playing as guest: progress won't be saved") and again at results ("Guest match: nothing was saved"), and nudges you to create a free account afterward.
- If you close the tab or app mid-match, your progress is kept on that device only, and next time you'll be explicitly asked whether to resume it or start fresh; never silently resumed or silently thrown away.
Simulated Players ("Smart Opponents")
Simulated players are not random guessers. Their behavior:
- Their first guess (or any guess before they've received feedback) is a random valid code.
- After that, they mentally narrow down every possible code still consistent with all feedback received so far, and pick randomly from whatever's left. They genuinely deduce; they just don't always make the single mathematically "best" next guess, only a guess that's still logically possible.
- They pause 2 to 15 seconds before each guess, so they don't feel instant or robotic giving other players time to think.
Naming pool can auto-grow beyond this list if needed, falling back to "Cipher2," "Cipher3," etc.
Our simulated players start at Rating 0, the same starting point as new accounts, so they begin on equal footing and differentiate through Ranked results over time.
Progression: Points & Rating
There are two separate progression numbers, tracked and leaderboarded independently. Worth keeping them conceptually distinct in any content you write.
Points
Earned at the end of every completed match (Except Private):
| Result | Standard | Hardcore |
|---|---|---|
| Win | +3 | +5 |
| Draw | +1 | +1 |
| Loss | +0 | +0 |
If a match is cancelled for going idle, everyone remaining loses 10% of their current Points balance (rounded to the nearest whole number).
Rating
A competitive, Elo-style number that only changes as a result of Ranked matches (win/lose/draw affects it; Casual and Private results never move it). Each pair of players in the match is compared head-to-head based on final placement, using a standard Elo expected-score calculation, and the results across all pairings are averaged into one rating change per player.
- New player accounts start at a Rating of 0. Players start at the same point, so both begin on equal footing.
- The idle-cancellation penalty (a flat -30 Rating) is applied even in Casual matches, not only Ranked.
Statistics (tracked per account)
Currently tracked and shown wherever match history/profile stats appear: matches played, matches won, matches lost, matches drawn, rounds won, times disconnected, and times a match was cancelled for inactivity. "Total guesses" and "correct guesses" on a Results or Match Details screen are always calculated fresh from that specific match, not pulled from a running lifetime total.
Achievements
Four achievements currently exist, shown on the Profile screen as locked/unlocked badges. All four are permanent: once earned, they stay earned for the life of the account.
| Key | Label | Criteria |
|---|---|---|
| HUNDRED_WINS | 100 Wins ✓ | 100 total match wins |
| SPEEDSTER | Speedster ⚡ | Won any match in under 90 seconds, start to finish |
| FLAWLESS_FIVE | Flawless x5 🎯 | Won 5 separate rounds on your very first guess of that round |
| FIVE_HUNDRED_MATCHES | 500 Matches 🏅 | 500 total matches played |
All four are styled in "green," the same tone as the rest of the app's success states.
Leaderboards
Two separate global leaderboards, matching the two progression numbers:
Each is shown as a top-3 "podium" (displayed in 2nd-1st-3rd order left to right) followed by a scrollable ranked list. If you're logged in, your own current rank is shown even if it's further down the list than what's currently visible.
Top 10 status
A Top 10 indicator is a live status tied to current Rating leaderboard rank, not a one-time unlock:
- Shown only while the player's current Rating rank is within the top 10.
- If they drop out of the top 10, the indicator is removed.
- If they re-enter the top 10 later, it's shown again.
Unlike the four permanent Achievements, this reflects standing at the time it's checked: earned and lost as rank changes, not kept forever.
Match History & Match Details
Match History (account required) lists your past matches, filterable by All / Ranked / Casual / Private / Wins / Losses, grouped by date ("Today," "Yesterday," then by date), loading more in pages as you scroll.
Opening an individual match shows:
- A round-by-round breakdown, including every round's secret code: codes are only ever revealed once the match is completely over, never mid-match.
- Each participant's rounds won, rating change, points earned, and whether they disconnected or forfeited.
- Totals for guesses made and correct (winning) guesses, calculated specifically for that match.
Accounts, Sign-In & Access
- Signing up and logging in is fast and secure using Google Sign-In, no separate username or password needed.
- Only one active session per account at a time. Logging in on a new device immediately signs out any other device that was logged in, with an on-screen message explaining why. If you had a match in progress on the session that got signed out, it counts as a forfeit.
- Deleting your account immediately scrubs your username, email, password, and display name, and signs you out everywhere. Because match history is shared with opponents, the underlying match/round records are kept (so opponents' history stays intact), just detached from any identifying information about you. Your own Rating, Points, and stats disappear from view either way.
- Guests (no account) can freely use Practice Mode, Support, and "How to Play." Trying to reach Multiplayer, Leaderboards, Match History, Private Rooms, or Profile shows a "sign up to unlock" screen with a short pitch and a one-tap path to Sign Up or Log In.
Support and Community
Support the Game: Help fund server costs, ongoing development, and new content. Every contribution directly powers the future of the project through our active payment system.
Hall of Fame: We feature a Hall of Fame to recognize top supporters across our Supporter, Backer, and Champion tiers.
Join the Community: Connect with fellow players, track development progress, and chat directly with the dev team on our Official Discord.
Visual & Brand Identity
- Name: guessIo, stylized in the app's own logo/wordmark as guessIo.
- Tagline: "Analyse → Outsmart → Crack the Code."
Pure black background; neon green as the primary accent (used for "correct," success, and active states), with cyan, purple, orange, and red used for secondary states, categories, and warnings. A faint green grid-line pattern sits behind every screen.
Overall read: a dark "hacker terminal" / command-center aesthetic, not playful, cartoonish, or pastel. This pairs with the naming vocabulary to form a consistent "codebreaker" theme worth carrying into any new copy, characters, or promotional material.
The guess board's colored-tile presentation makes deduction feedback easy to scan at a glance, even though the content is always digits.
Screen Map
| Screen | Who can reach it | Purpose |
|---|---|---|
| Login / Register / Forgot Password / Reset Password | Everyone | Account access |
| Dashboard | Signed-in users | Home base: stats strip, Play button, recent matches, top players |
| Guest Home | Guests | Home base for guests: Play Solo, "sign up to unlock" tiles |
| Select Match (Play) | Signed-in users | Choose Casual / Ranked / Private, difficulty, player count |
| Practice Mode (Play, guest) | Guests | Choose Vs Computer / Pass & Play, difficulty, round length |
| Matchmaking | Signed-in users | Queue/waiting screen for Casual & Ranked |
| Private Room | Signed-in users | Create/join a room by code, lobby, host controls |
| Gameplay / Guest Gameplay | Whoever's in a match | The live guessing screen |
| Round Result | Whoever's in a match | Interstitial shown between rounds |
| Results / Guest Results | Whoever finished a match | Outcome, stats, rating/points earned |
| Profile | Signed-in users | Identity, stats, achievements, account actions |
| Match History / Match Details | Signed-in users | Past matches list and round-by-round breakdown |
| Leaderboards | Signed-in users (viewable per-code without account too) | Rating & Points rankings |
| Sign-Up Gate | Guests | Shown when a guest taps a locked feature |
| Support and Community | Everyone | Support the game's development, Hall of Fame & Discord community link |
| Error screens | Everyone | No connection, server error, room not found, 404, maintenance, session expired |