Quorix

A full multiplayer gaming platform built in Java, using BlueJ, as a school project. 50+ playable games, ELO ratings, a party system, tournaments, and one server, run by its owner, that everyone connects to.

New here, or not a programmer? HOW_QUORIX_WORKS.md explains the whole project in plain language, no code-reading required.

See FEATURES.md for the complete, current feature list, and ROADMAP.md for what's planned next. The summaries below are kept short on purpose.

Running it

Without BlueJ (fastest way to just play):

java -jar QuorixServer.jar

then, in a separate terminal (or on another computer):

java -jar QuorixClient.jar

The server has to be running before a client can connect. On a weaker machine, use Run-QuorixServer-LowEnd.bat/.sh and Run-QuorixClient-LowEnd.bat/.sh instead — same thing, with JVM flags tuned for lower memory and a lighter garbage collector.

Double-click it (Windows): Quorix.bat and QuorixServer.bat don't require Java on your PATH — they check the common install locations (BlueJ's own bundled JDK included) automatically and use whichever one they find, so there's nothing to configure on any machine you copy these to. Run-*-LowEnd.bat do the same auto-detection, plus the low-memory JVM flags for older hardware.

Pin it to your taskbar: Windows won't let you pin a .bat file directly (that option is greyed out for script files) — run Create-Desktop-Shortcut.bat once instead. It creates proper Windows shortcuts on your Desktop (with the Quorix icon) for both the client and the server; right-click either one and choose "Pin to taskbar."

With BlueJ: open QuorixServer and QuorixClient as separate projects, compile the server first, run ServerMain (headless - no window opens, just a console log line once it's listening), then run Quorix from one or more client instances.

Obfuscated client for release (Mac/Linux, optional): ./build.sh --obfuscate also writes QuorixClient-release.jar - the same client with class/method/field names scrambled and debug info removed. It needs a full JDK (with a jmods/ folder) and downloads ProGuard once into .tools/ (checksum-verified). A speed bump against casual copying, not a lock: the server stays the authority. The build verifies that nothing sent over the wire changed (proguard/WireCompatCheck). There is no build.bat equivalent yet.

Building fresh jars from source (no BlueJ): run build.sh (Mac/Linux) or build.bat (Windows) from the repo root. Compiles both projects and overwrites QuorixClient.jar/QuorixServer.jar in place, stamped with the version from the VERSION file. This is what actually produces the jars above - BlueJ's own "Create Application" export still works too, this is just a one-command alternative that doesn't need BlueJ installed at all.

Either way, the client's first screen asks whether you want to host a server or connect to one — see below.

The Windows app (Quorix.exe, no Java needed): the repo's Windows app workflow builds it - on GitHub, so no Windows PC is required. Open the repo's Actions tab, choose Windows app, Run workflow, and (optionally) type the server's hostname, e.g. example.org. When it finishes, download two artifacts: Quorix-Windows (a zip: unzip anywhere, run Quorix\Quorix.exe) and Quorix-server-update (Quorix.jar, see below). The exe is unsigned, so Windows SmartScreen shows "Windows protected your PC" the first time: More info, then Run anyway.

Players never type an address. The app connects to the server named in server.txt (a single line: host or host:port) next to the app - the workflow writes it from the hostname you typed, and you can edit it afterwards. With no file it uses the built-in default, the official server (its address is set in net/ServerAddress). Changing the machine the server runs on only needs the hostname's DNS record updated, not a new client.

Updating everyone after v1: build a new app with the workflow, copy its Quorix.jar next to QuorixServer.jar on the server (no restart needed). Every time the app starts, before its first screen, it asks the server whether the file differs from its own, downloads the new one and swaps it in - so even a computer that restores itself to the original install at reboot ends up on the newest version (it needs the network at that moment; otherwise it starts as it is). A running app can also be updated by hand: Settings > Check for updates, or the Restart to update button that appears in the top bar once a download has finished. The old client is kept as client/QuorixClient.bin.old, and if a new one fails to load the app goes back to the old one by itself. Always replace Quorix.jar with the file from the same kind of build the players have - the check compares exact file contents. To roll back, put the old Quorix.jar back. If you run the plain jar instead (Quorix.bat), the update arrives as QuorixClient.jar.new and the launcher script renames it in.

Hosting and connecting

  • Hosting is a dedicated-server thing, not a client feature. Only java -jar QuorixServer.jar starts a server. The ordinary QuorixClient.jar a player runs has no "host a server" option anywhere in it (removed 2026-09-25) — running a server means running the actual server program, deliberately, not something any player can casually switch on from Settings.
  • One server, one account store. Whichever server you connect to is the source of truth for its own accounts, matches, and progress — there's no cross-server syncing to reason about, and no "main" vs. "satellite" distinction. Simple to run, and simple to host somewhere always-on (e.g. a single cloud VM).
  • Switching servers is still easy. The in-app server switcher (Settings → Switch Server) lets you save addresses and jump between servers without editing any code, and re-authenticates you automatically if that server already knows your account.

Default port is 7777, but this is fully configurable via the same switcher.

The games

Online multiplayer (real opponents, ELO-rated unless noted): - Chess — full rules including castling, en passant, checkmate/stalemate detection. Resign or offer a draw mid-game. Spectate any live match, or replay a finished one move-by-move. - Battleship — classic hunt-and-sink, 1v1. Spectators see both fleets fully revealed (there's nothing to hide once you're just watching); replays step through every shot in order. - Rock Paper Scissors — best of 5, simultaneous blind moves each round. Spectator and replay support included. - Connect Four — classic 7×6 drop-and-connect, standard rules. - Checkers — standard American rules, mandatory captures and multi-jump continuation, kinging. - Racing — 3 to 6 players, shared track, with power-ups: shields, speed boosts, and coin pickups. Not ELO-rated — scored and ranked on a leaderboard instead. - Zombie Survival — 2 to 4 players, co-op wave shooter — same seed, independent local simulation. Not ELO-rated — survive all 8 waves for a full coin reward. - Space Battle — 3 to 6 players, arcade dogfight against asteroids and enemy fighters. Not ELO-rated — ranked by score. - Fight Arena — 1v1, 2v2, 3v3, or free-for-all. Queue solo or with a party (your party always ends up on the same team). 2v2/3v3 also support a lightweight team tournament: register your party, wait for an opposing party, winner takes it. - Impostor Ship — round-based social deduction with a small group. - Tic-Tac-Toe — online ranked matches, or practice offline against a simple AI. - Telephone — 4 to 8 players, a Gartic-Phone-style draw/guess chain: write a phrase, pass it on, someone draws it, the drawing gets passed on, someone guesses it, and so on until every chain gets revealed start to finish. Purely for fun — no ranking, everyone earns a flat reward just for playing.

Solo tournaments (Battleship & Rock Paper Scissors only, since both games always produce a clear winner): 4-player single-elimination brackets, browsable and joinable from the Tournaments page.

Rematch: after any Chess, Battleship, or RPS match, challenge the same opponent again with one click — no need to re-queue.

Single-player (no server needed to play, though wins/scores still get tracked if you're logged in): Snake, Block Stack, 2048, Pong, Dino Dash, Crossing Road, Puzzle Quest, Aim Trainer, and RPS against a simple AI. Snake, Block Stack, and Dino Dash all support pausing mid-game (press P).

Also playable, ELO-rated 1v1 (see FEATURES.md for full details on each): Dots and Boxes, Reversi/Othello, Memory Match, Air Hockey, Word Duel, Dice Duel, Snake Arena, Block Stack Duel, Square Wars, Fusion Grid, Typing Duel, Signal Grid, and Card Rush.

More single-player (no server needed): Mine Grid, Sudoku, Simon Says, Whack-a-Mole, Gem Match (an original match-3 - swap gems, clear lines, chain cascades for bonus score), Maze Chase (an original maze-and-chasers game - clear every dot, dodge the chasers, grab a power pellet to turn the tables for a few seconds), Brick Breaker (bounce the ball off the paddle to smash the wall of bricks), Flap Flyer (tap to flap upward, gravity pulls you back down, thread the gaps between scrolling pipes), Galaxy Defender (an original fixed-shooter - clear each marching wave of enemies before they reach your line, wave after wave), Word Guess (guess the hidden 5-letter word in 6 tries with letter-position feedback), Bubble Shooter (aim and fire colored bubbles into a hex grid, matching 3+ to pop them and drop anything left floating), Lights Out (click a light to toggle it and its neighbors, turn every light off to solve the puzzle), Peg Solitaire (the classic cross-shaped board - jump pegs over each other until none can jump again, ideally down to just one left in the center), Classic Solitaire (the traditional card-solitaire patience game - build the four suit foundations up from Ace to King), Five Dice (roll five dice up to three times a turn, holding what you like, and score into one of 13 categories), and Mancala (the classic sowing game - built-in AI opponent, standard Kalah capture and bonus-turn rules).

Everything else

  • Accounts & progression — coins (now earned from every game, not just a handful — see FEATURES.md), daily login streaks, an ELO rating per competitive game, a shop for cosmetics (username colors, chat badges), avatars (upload an image or paint one directly in-app), and achievements tied to real milestones.
  • Social — friends (search/filter/pin), direct messages, group chat with a Discord-style redesign (avatars, grouped messages, typing indicators, unread badges, drag-and-drop file attach), party invites, high-score sharing, and a community game-suggestions board.
  • Notifications — a bell icon with a live feed, achievement unlock toasts, notification sounds, and a one-click "Clear All."
  • Customization — 11 full themes including an animated Glitch mode; every game now renders with a fixed palette regardless of theme choice; the mode-select screen remembers which option you picked last time for each game.
  • Performance — a Settings toggle for lower-end hardware (reduced rendering quality, halved frame rate) plus a live FPS counter, on top of the existing -LowEnd launcher scripts.
  • Admin & moderation tools — a real Admin Panel (player role management, an audit log), moderators, staff-colored chat usernames, and a feedback system.
  • Quality of life — a global search bar, Escape closes every dialog, confirm-before-close on any active match, and auto-reconnect after a dropped connection.

Full details on all of the above: FEATURES.md.

Repo structure

Three top-level folders:

  • QuorixClient/ — built and shipped as QuorixClient.jar (Main-Class: Quorix). This is what someone who just wants to play runs, and it's the edit source of truth for anything shared between the two Java projects: make changes here first.
  • QuorixServer/ — built and shipped as QuorixServer.jar (Main-Class: ServerMain). Headless: no GUI, no client code at all. Runs unattended on a real machine (a cloud VM with no display included) rather than opening a login window the way earlier versions did.
  • website/ — the public website (Python/Flask), unrelated to the two Java projects above. See website/README.md.

QuorixClient/ and QuorixServer/ are not identical copies of each other:

Why they're different now. Earlier, ServerMain also opened a full client login window in-process the moment hosting started, so the server needed almost the entire client UI just to do that - both folders carried the same ~350 files. That's gone: ServerMain now only starts GameServer and blocks, nothing else. Every class it actually needs was found by compiling just that one entry point against the full source tree and keeping only what the compiler pulled in - not guesswork - which turned out to be about 100 files: net, account, social, admin, economy, games (the rule engines and match managers, not any Window/Dialog class), and ai.knowledge (the live Trivia Blitz lookups - the only part of the ai package the server needs, since practice-mode bots run entirely on the client and never touch the server at all). The entire ui, theme, and pages packages are gone from QuorixServer/, along with every game's own Window/Dialog class and the ai.search/ai.grid/ai.steering bot engine.

Only genuinely shared files get mirrored now. Changing a network message type, a game's rule engine, or an account/economy class → edit it in QuorixClient/, then copy it into QuorixServer/ too, same as before. Changing UI-only code (a page, a dialog, a theme, a game's Window class) → it only exists in QuorixClient/, there's nothing to copy.

Someone who wants the old "start a server and get a playable window in the same process" behavior back runs QuorixServer.jar and QuorixClient.jar side by side instead - two processes on the same machine, same practical effect, without QuorixServer/ needing to carry a full copy of the client's UI to do it.

Packages (in QuorixClient/; QuorixServer/ only has the ones actually needed - see above):

  • net — networking core: Message, MessageType, NetworkManager, ClientHandler, GameServer, connection state
  • account — accounts, auth, sessions, profile viewing
  • theme — the theming system and all 11 themes
  • ui — generic reusable widgets (buttons, panels, dialogs not tied to a specific feature)
  • pages — the app's top-level navigable pages (Home, Games, Chat, Settings, Admin, etc.)
  • economy — coins, cosmetics, achievements, leaderboards, local device preferences
  • social — chat, friends, party, moderation-facing dialogs
  • admin — admin log, feedback, game suggestions
  • games — every game's logic/window/match classes, plus the shared game-launching/registry/tournament/replay infrastructure
  • ai — bot AI: ai.search/ai.grid/ai.steering power practice mode entirely offline on the client; ai.knowledge (live Trivia Blitz lookups) is the one part that's also needed server-side

Only Quorix.java and ServerMain.java — the two actual entry points java -jar runs — stay in the default (unpackaged) package; everything else lives in one of the packages above. If you're adding a new class, put it in the package that matches what it's for, and add package <name>; as its first line.

  • QuorixClient.jar / QuorixServer.jar — pre-built runnable JARs; rebuild with build.sh/build.bat
  • test.sh — runs the committed regression suite (QuorixServerTests/, a sibling to QuorixServer/, never shipped in the jar) against a fresh QuorixServer build; nonzero exit if anything fails
  • VERSION — the current release number (semver), read by the build script and shown in-app
  • Run-*-LowEnd.* — launcher scripts tuned for weaker hardware
  • Sync-Feedback.sh/.bat — pushes bug reports and game suggestions the server has collected back to this repo so they can be read here, with every player's username replaced by "player" first (the repo is public). Only anonymized copies in feedback-for-review/ are committed; the originals and everything else stay on the server.

Source: README.md on GitHub