add multiplayer and playing against bots by aaravmaloo · Pull Request #50 · vyrx-dev/toofan

aaravmaloo · 2026-05-05T22:15:25Z

Competitive Racing (Multiplayer and AI Bots)

This PR implements the complete competitive racing framework for Toofan, including a dedicated multiplayer server and an AI-driven bot system. These features transition the game from a solo typing tool to a real-time competitive platform.

Core Features

1. Multiplayer Racing System

Developed a high-performance, independent race server to handle real-time multiplayer sessions.

Architecture: A centralized Hub/Room management system built from scratch.
Protocol: Real-time communication via Server-Sent Events (SSE) for low-latency progress broadcasting.
Session Management: Implemented heartbeats and "kick-on-join" logic to prevent ghost sessions and ensure immediate reconnection stability.
Lobby System: Support for configurable room sizes and automatic matchmaking.

2. AI Ghost Racers

Introduced a bot system to provide a competitive experience even in offline mode.

Personalized Difficulty: Bots can automatically scale their speed based on the user's last 10 tests (Personalized Strategy) or fixed levels (Easy, Medium, Hard).
Realistic Movement: Implemented "jitter" and varying WPM profiles for bots to simulate human-like typing patterns.
Ghost Cursors: Visual parity with multiplayer sessions, showing real-time rankings and progress bars for all bot participants.

3. TUI Integration

Updated the Bubble Tea model and view dispatch logic to handle complex race states.

Race View: New real-time racing UI featuring live leaderboards and multi-track progress bars.
Results Screen: Detailed post-race breakdown showing placements, rank, and WPM for all participants.
Centralized Content: Integrated the race server with the project's internal wordlist logic, ensuring consistent test material between local and online modes.

Technical Improvements

Stability: Fixed critical double-unlock race conditions in the server's room logic.
Cleanup: Robust session termination using deferred cleanup and connection monitoring.
Independence: The race server is a standalone module with its own embedded assets, requiring zero external dependencies for deployment.

Verification

Verified multiplayer connectivity across multiple terminals using localhost and public IP addresses.
Validated bot scaling logic across various user skill levels.
Tested server resilience by simulating sudden client disconnects and rapid reconnects.

Deployment Status

The server-side code has been successfully deployed on my server, to save deployment headache and server costs. The server has a 99.99% uptime and is running continuously.
The current deployment on the server can support up to 50 players simultaneously.
The deployed server-code listens on the port 8525 and can fully run independently without any extra toofan code.
The port 8525 on the deployed server was exposed via cloudflare. The base url for the multiplayer server of Toofan is: http://toofan-race.pikapp.in
The tunnel is exposed via cloudflare tunnels, by the domain I own.

the `main.go` is the actual path manager (somewhat of a API), protocol stores all the `structs` required and `room.go` keeps tracks of players and manages the core functionality of multiplayer

handles connections and rooms, while room.go handles the actual gameplay inside those rooms.

`usrname` str correctly identifies each player uniquely. serverURL needs to be stored for connections to the server while playing multiplayer

vyrx-dev · 2026-05-06T03:56:01Z

Attach a video with it please

vyrx-dev · 2026-05-06T06:02:33Z

I tried it locally and it looks so cool 🔥

vyrx-dev · 2026-05-06T08:57:14Z

multiplayer mode is not working... have you tested it on your machine?

vyrx-dev · 2026-05-06T09:34:34Z

I’ve created a toofan-online branch and updated the README with your changes. Make sure you create the PR against that branch only.

vyrx-dev · 2026-05-06T13:37:18Z

what is bot percentage here means? accuracy, completion or anything else?

aaravmaloo · 2026-05-06T14:09:48Z

So basically multiplayer won't work if your joining two sessions frkm the same device.
To test multiplayer, you need separate devices. I made it so because we don't have the same person playing as 2 or more players.

vyrx-dev · 2026-05-06T14:13:26Z

from the same device.

what if two different people using same wifi network?

vyrx-dev · 2026-05-06T14:21:09Z

Btw, for letter tracking, which do you think looks cleaner: caret tracking with a different color or the current look?

switched to cloudflare tunnel, since safer, and faster

@vyrx-dev

big changes made. - now there are rooms - rooms can be public or private. - private rooms require a code to join - the host can configure settings for the room these changes were made by the feedback of @vyrx-dev

- after multiplayer was over, toofan would just freeze. the fix involved in the server responding with a status of over and then the client displaying the correct results. - added bot-like gameplay, with ghost cursors and colored list while playing multiplyer

…s in multiplayer

…when the user tries to play another

vyrx-dev · 2026-05-07T18:11:50Z

what's the status?

aaravmaloo · 2026-05-07T18:14:09Z

I think its ready for merging. you can check the code and it was testing locally. 👍

… clients

…lly start the race

…oms. fixed an issue where the multiplayer states would not update

… words mode was selected

… and bots mode

programmersd21 · 2026-05-09T05:31:32Z

@vyrx-dev, I tried it out too, it's awesome af! pls merge it, would love it to be in upstream! ❤️🔥

Copilot

Pull request overview

This PR introduces competitive racing to Toofan by adding (1) a standalone SSE-based multiplayer race server, and (2) local AI bot racers, plus the TUI/client-side wiring to render races (ghost cursors, race bars, lobby/results views) and persist multiplayer settings.

Changes:

Added a standalone race_server/ Go module implementing rooms, lobby/countdown/race state, and an SSE join endpoint with HTTP progress updates.
Added a local AI bot system and race UI elements (bot picker, ghost cursors, race bars, bot results).
Added an in-app multiplayer flow (room creation/joining/quick-match, lobby UI, progress reporting, results) plus config persistence for username/server URL.

Reviewed changes

Copilot reviewed 90 out of 90 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
README.md	Adds FAQ entries for online/bots and a contributors section.
race_server/go.mod	Defines standalone race server module.
race_server/main.go	Adds HTTP endpoints for join/progress/start/online/health.
race_server/hub.go	Implements hub + SSE join handler + matchmaking logic.
race_server/protocol.go	Defines JSON protocol types and message wrapper.
race_server/room.go	Implements room state, countdown/start, progress + finish broadcasting.
race_server/words.go	Embeds and loads word/snippet content; generates race text.
race_server/data/english/easy.txt	Adds embedded easy English word list for races.
race_server/data/english/medium.txt	Adds embedded medium English word list for races.
race_server/data/english/hard.txt	Adds embedded hard English word list for races.
race_server/data/go/00_basics.go	Adds Go snippet content for code-mode races.
race_server/data/go/01_http_server.go	Adds Go snippet content for code-mode races.
race_server/data/go/02_concurrency.go	Adds Go snippet content for code-mode races.
race_server/data/go/03_error_handling.go	Adds Go snippet content for code-mode races.
race_server/data/go/04_interfaces.go	Adds Go snippet content for code-mode races.
race_server/data/go/05_maps_slices.go	Adds Go snippet content for code-mode races.
race_server/data/go/06_structs.go	Adds Go snippet content for code-mode races.
race_server/data/go/07_closures.go	Adds Go snippet content for code-mode races.
race_server/data/go/08_json.go	Adds Go snippet content for code-mode races.
race_server/data/go/lessons/basics.go	Adds Go lesson snippet content for code-mode races.
race_server/data/javascript/00_variables.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/01_fetch_api.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/02_array_methods.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/03_dom_selection.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/04_promises.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/05_classes.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/06_destructuring.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/07_arrow_closures.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/08_events.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/09_error_handling.js	Adds JS snippet content for code-mode races.
race_server/data/javascript/10_storage.js	Adds JS snippet content for code-mode races.
race_server/data/typescript/01_union_intersection.ts	Adds TS snippet content for code-mode races.
race_server/data/typescript/02_generics_constraints.ts	Adds TS snippet content for code-mode races.
race_server/data/typescript/03_mapped_conditional.ts	Adds TS snippet content for code-mode races.
race_server/data/typescript/04_template_literal.ts	Adds TS snippet content for code-mode races.
race_server/data/typescript/05_async_error_handling.ts	Adds TS snippet content for code-mode races.
race_server/data/python/01_file_handling.py	Adds Python snippet content for code-mode races.
race_server/data/python/02_requests_api.py	Adds Python snippet content for code-mode races.
race_server/data/python/03_list_dict_comprehension.py	Adds Python snippet content for code-mode races.
race_server/data/python/04_async_io.py	Adds Python snippet content for code-mode races.
race_server/data/python/05_data_processing.py	Adds Python snippet content for code-mode races.
race_server/data/rust/01_divide.rs	Adds Rust snippet content for code-mode races.
race_server/data/rust/02_struct.rs	Adds Rust snippet content for code-mode races.
race_server/data/rust/03_vectors.rs	Adds Rust snippet content for code-mode races.
race_server/data/rust/04_files.rs	Adds Rust snippet content for code-mode races.
race_server/data/rust/05_closures.rs	Adds Rust snippet content for code-mode races.
race_server/data/java/01_stream_pipeline.java	Adds Java snippet content for code-mode races.
race_server/data/java/02_optional_patterns.java	Adds Java snippet content for code-mode races.
race_server/data/java/03_completable_future.java	Adds Java snippet content for code-mode races.
race_server/data/java/04_record_pattern.java	Adds Java snippet content for code-mode races.
race_server/data/java/05_concurrent_collections.java	Adds Java snippet content for code-mode races.
race_server/data/c/01_file_io.c	Adds C snippet content for code-mode races.
race_server/data/c/02_pointer_usage.c	Adds C snippet content for code-mode races.
race_server/data/c/03_dynamic_memory.c	Adds C snippet content for code-mode races.
race_server/data/c/04_struct_patterns.c	Adds C snippet content for code-mode races.
race_server/data/c/05_standard_library.c	Adds C snippet content for code-mode races.
race_server/data/cpp/01_file_io.cpp	Adds C++ snippet content for code-mode races.
race_server/data/cpp/02_vector_patterns.cpp	Adds C++ snippet content for code-mode races.
race_server/data/cpp/03_async_thread.cpp	Adds C++ snippet content for code-mode races.
race_server/data/cpp/04_modern_features.cpp	Adds C++ snippet content for code-mode races.
race_server/data/cpp/05_stl_algorithms.cpp	Adds C++ snippet content for code-mode races.
race_server/data/csharp/01_linq_queries.cs	Adds C# snippet content for code-mode races.
race_server/data/csharp/02_async_await.cs	Adds C# snippet content for code-mode races.
race_server/data/csharp/03_file_handling.cs	Adds C# snippet content for code-mode races.
race_server/data/csharp/04_dependency_injection.cs	Adds C# snippet content for code-mode races.
race_server/data/csharp/05_collections.cs	Adds C# snippet content for code-mode races.
race_server/data/dart/00_classes.dart	Adds Dart snippet content for code-mode races.
race_server/data/dart/01_async.dart	Adds Dart snippet content for code-mode races.
race_server/data/dart/02_collections.dart	Adds Dart snippet content for code-mode races.
race_server/data/dart/03_mixins.dart	Adds Dart snippet content for code-mode races.
race_server/data/lua/00_tables.lua	Adds Lua snippet content for code-mode races.
race_server/data/lua/01_metatables.lua	Adds Lua snippet content for code-mode races.
race_server/data/lua/02_file_io.lua	Adds Lua snippet content for code-mode races.
race_server/data/lua/03_coroutines.lua	Adds Lua snippet content for code-mode races.
race_server/data/shell/00_boilerplate.sh	Adds shell snippet content for code-mode races.
race_server/data/shell/01_conditionals.sh	Adds shell snippet content for code-mode races.
race_server/data/shell/02_loops.sh	Adds shell snippet content for code-mode races.
race_server/data/shell/03_docker_git.sh	Adds shell snippet content for code-mode races.
race_server/data/shell/04_text.sh	Adds shell snippet content for code-mode races.
internal/game/bot.go	Adds local bot generation + ticking + placement logic.
internal/game/client.go	Adds multiplayer SSE client + HTTP progress/start calls.
internal/game/storage.go	Persists multiplayer username/server URL in config.
internal/tui/model.go	Adds state + update loop wiring for bots and multiplayer sessions.
internal/tui/typing.go	Adds ghost cursors + race bars + keybinds for bots/multiplayer.
internal/tui/text.go	Extends text rendering to support ghost cursor styling.
internal/tui/race.go	Adds bot picker UI + bot race bar/results rendering.
internal/tui/online.go	Adds multiplayer room flow (create/join/quick match) + lobby/results UI.
internal/tui/results.go	Adds bot/multiplayer results integration + reset/disconnect logic.
internal/tui/picker.go	Updates theme picker to match expanded config format.
internal/tui/profile.go	Tweaks PB heading label in profile view.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+func (c *RaceClient) SendProgress(progress float64, wpm float64) error {
+	c.mu.Lock()
+	if c.closed {
+		c.mu.Unlock()
+		return nil
+	}
+	c.mu.Unlock()
+
+	body := map[string]interface{}{
+		"name":     c.name,
+		"room":     c.room,
+		"progress": progress,
+		"wpm":      wpm,
+	}
+	data, _ := json.Marshal(body)
+
+	resp, err := c.client.Post(c.serverURL+"/race/progress", "application/json", bytes.NewReader(data))
+	if err != nil {
+		return err
+	}
+	resp.Body.Close()
+	return nil
+}


+		// update local player's progress for immediate feedback
+		for i := range m.racePlayers {
+			if m.racePlayers[i].IsUser {
+				m.racePlayers[i].Progress = userProg
+				break
+			}
+		}
+		out = append(out, "", viewOnlineRaceBar(p, m.racePlayers, textWidth-4))


+	case "joined":
+		var payload game.LobbyPayload
+		if err := json.Unmarshal(msg.Payload, &payload); err != nil {
+			return m, nil
+		}


+	case "start":
+		var payload game.StartPayload
+		if err := json.Unmarshal(msg.Payload, &payload); err != nil {
+			return m, nil
+		}


+func (h *hub) removeClient(c *client) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+


+		// auto-match in public rooms.
+		// no_rooms=true means queue for random 1v1 only (never join custom-sized rooms).
+		for _, ex := range h.rooms {
+			if ex.started || ex.pin != "" || len(ex.players) >= ex.maxPlayers {
+				continue


+func (c *RaceClient) Join(roomID, pin string, isCreate bool, size int, difficulty, mode, lang string, duration int, autoStart bool) error {
+	url := fmt.Sprintf("%s/race/join?name=%s", c.serverURL, c.name)
+	if !isCreate && roomID == "" {
+		url += "&no_rooms=true"
+	}
+	if roomID != "" {
+		url += "&room=" + roomID
+	}
+	if pin != "" {
+		url += "&pin=" + pin
+	}
+	if isCreate {
+		url += "&is_create=true"
+		url += fmt.Sprintf("&size=%d&difficulty=%s&mode=%s&lang=%s&duration=%d&auto_start=%t", size, difficulty, mode, lang, duration, autoStart)
+	}


+func (c *RaceClient) Close() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.closed {
+		return
+	}
+	c.closed = true
+	close(c.done)
+}


+				if m.raceState == onlineRacing && m.raceClient != nil {
+					prog := 0.0
+					if len(m.game.Text()) > 0 {
+						prog = float64(len(m.game.Input())) / float64(len(m.game.Text()))
+					}
+					wpm := m.game.Stats().WPM
+					go m.raceClient.SendProgress(prog, wpm)
+				}


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

vyrx-dev · 2026-06-07T15:11:19Z

@aaravmaloo i am not good with server side things so please check suggestions made by copilot especially those are labeled as high

aaravmaloo · 2026-06-07T20:49:25Z

@vyrx-dev well I think its suggestion are valid, but it does work perfectly and I see no need to consider those changes. If you really want to, feel free to take those suggestions, but its suggestions pretty negligible.

programmersd21 · 2026-07-04T14:10:54Z

@vyrx-dev @aaravmaloo when is it comin' out guyzzz??? would be so cool af daymmmmm 😭

vyrx-dev · 2026-07-04T14:13:46Z

It's available...you can just checkout the PR branch and try

As you can see it's not a small change so I have to review too many lines and it takes time (actually I am very busy with my freelance work)

You have to wait a little bit more 😅 for the package release

aaravmaloo · 2026-07-04T14:25:44Z

@vyrx-dev I thought we were gonna keep this on a toofan-online branch, right?

vyrx-dev · 2026-07-04T14:26:58Z

@vyrx-dev I thought we were gonna keep this on a toofan-online branch, right?

Yes

programmersd21 · 2026-07-04T14:40:31Z

It's available...you can just checkout the PR branch and try

As you can see it's not a small change so I have to review too many lines and it takes time (actually I am very busy with my freelance work)

You have to wait a little bit more 😅 for the package release

ok np

aaravmaloo · 2026-07-04T15:12:37Z

seems like a good choice. if you do have questions, on how this works, etc, lemme know!

aaravmaloo added 11 commits May 6, 2026 03:30

update the README.

9c38442

create core logic for the server-side multiplayer code

6cbe7b6

the `main.go` is the actual path manager (somewhat of a API), protocol stores all the `structs` required and `room.go` keeps tracks of players and manages the core functionality of multiplayer

create independent go mod for server-side code

36e4a6f

create logic for words joiner in multiplayer

5fa1ebc

write the actual wordlist where the server will get words from

12c2057

create hub.go, a core component for multiplyer

35c9b72

handles connections and rooms, while room.go handles the actual gameplay inside those rooms.

create TUI components for multiplayer and bots

bdfed13

edit all the three files to support bot and multiplyr changes

4787e08

update storage to store usrname and serverURL

a898edd

`usrname` str correctly identifies each player uniquely. serverURL needs to be stored for connections to the server while playing multiplayer

write main logic for playing against bots

d553d05

update model to include my changes and additions made to toofan.

e754b33

vyrx-dev assigned vyrx-dev, aaravmaloo and Copilot and unassigned vyrx-dev May 6, 2026

aaravmaloo changed the base branch from master to toofan-online May 6, 2026 14:10

Merge branch 'toofan-online' into master

3a7ee2e

aaravmaloo added 5 commits May 6, 2026 21:03

update the defaultserverURL to use my cloudflare tunnel

eb92495

switched to cloudflare tunnel, since safer, and faster

Merge branch 'master' of https://github.com/aaravmaloo/toofan

572b9c2

update to display the stats after race more cleanly and more info

7538967

add rooms and ability to join rooms and also to customize room setting

c644710

big changes made. - now there are rooms - rooms can be public or private. - private rooms require a code to join - the host can configure settings for the room these changes were made by the feedback of @vyrx-dev

add better result outputs

56d7604

aaravmaloo added 5 commits May 7, 2026 20:04

rename personal bests to pb to keep it minimal

940caa5

update multiplayer (while playing aspect) to look like bots interface

d34db98

fix bug where different words were being presented to both the player…

b38f1c5

…s in multiplayer

fix a bug where after playing 1 multiplayer match, the TUI got stuck …

d2933f6

…when the user tries to play another

aaravmaloo added 8 commits May 8, 2026 00:01

add data to race_server so that it can indepently provide wordlist to…

0144d18

… clients

make the server enforce rules to make sure that all the clients acuta…

52b17d3

…lly start the race

add a empty lobby/quick match which can be played without creating ro…

eed618b

…oms. fixed an issue where the multiplayer states would not update

add option for host to autostart or manually start rooms

dee15fd

fixed an issue where the waiting room would show languages even while…

c0a77e2

… words mode was selected

update the readme to add contributors section and add FAQs for online…

4d06d61

… and bots mode

fix rendering FAQs issues with readme

641ef9c

update readme to remove contrib.rocks as requested by @vyrx-dev

51377c0

aaravmaloo added feature add New feature or request in-review tag indicating the PR is in review labels May 7, 2026

vyrx-dev requested a review from Copilot June 7, 2026 15:01

Copilot started reviewing on behalf of vyrx-dev June 7, 2026 15:01 View session

Copilot AI reviewed Jun 7, 2026

View reviewed changes

docs update

318e2ae

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Uh oh!

Conversation

aaravmaloo commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Competitive Racing (Multiplayer and AI Bots)

Core Features

1. Multiplayer Racing System

2. AI Ghost Racers

3. TUI Integration

Technical Improvements

Verification

Deployment Status

Uh oh!

vyrx-dev commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vyrx-dev commented May 6, 2026

Uh oh!

vyrx-dev commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vyrx-dev commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vyrx-dev commented May 6, 2026

Uh oh!

aaravmaloo commented May 6, 2026

Uh oh!

vyrx-dev commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vyrx-dev commented May 6, 2026

Uh oh!

vyrx-dev commented May 7, 2026

Uh oh!

aaravmaloo commented May 7, 2026

Uh oh!

programmersd21 commented May 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

vyrx-dev commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaravmaloo commented Jun 7, 2026

Uh oh!

programmersd21 commented Jul 4, 2026

Uh oh!

vyrx-dev commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaravmaloo commented Jul 4, 2026

Uh oh!

vyrx-dev commented Jul 4, 2026

Uh oh!

programmersd21 commented Jul 4, 2026

Uh oh!

aaravmaloo commented Jul 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aaravmaloo commented May 5, 2026 •

edited

Loading

vyrx-dev commented May 6, 2026 •

edited

Loading

vyrx-dev commented May 6, 2026 •

edited

Loading

vyrx-dev commented May 6, 2026 •

edited

Loading

vyrx-dev commented May 6, 2026 •

edited

Loading

vyrx-dev commented Jun 7, 2026 •

edited

Loading

vyrx-dev commented Jul 4, 2026 •

edited

Loading