VIMVIM Racing

https://github.com/MumenOsman/vimvim-racing

Game Features

Core Racing

• 2D top-down perspective with two hand-crafted race circuits
• Smooth vehicle physics including acceleration, braking, steering, and momentum
• Multi-surface friction: asphalt (full grip), kerbs (reduced grip), and gravel/grass (significantly reduced grip)
• Soft cushion collision bounce between cars: vehicles push apart on impact with a moderate speed penalty rather than grinding to a halt
• Collision sound plays on initial contact only and does not loop during sustained proximity

Lap and Scoring System

• Configurable lap count: choose 1, 2, 3, 5, 7, or 10 laps from the lobby before the race starts
• Eight-point checkpoint gate system that validates correct circuit direction and prevents shortcutting
• Real-time race position display (1st through 4th) updated every frame
• Best lap time tracking for each player
• Final race standings and winner announcement at the end

Hazards and Power-Ups

• Oil slick zones: driving over one causes your vehicle to lose traction and spin out briefly
• Boost pad: a pickup item that spawns at a fixed strategic location on the track; collecting it grants a temporary speed boost
• UFO Abduction perk: a rare item that teleports your vehicle forward two checkpoint sectors, skipping road ahead of you
• Rocket perk: fires a projectile forward that causes a spin-out on impact with another vehicle

AI Opponents

• Bot vehicles use waypoint navigation to follow the racing line autonomously
• Bots participate in all physics and collision systems equally with human players
• Bots also receive perks and item pickups on a timed random interval

Multiplayer

• Supports 2, 3, or 4 simultaneous human players
• Each player joins from their own browser
• All player positions, angles, and speeds are synchronized in real time over WebSockets
• 30 Hz server-to-client state broadcasting with 60 FPS client-side interpolation to keep movement smooth between updates
• Players can join from any network using an internet tunnel (ngrok or localtunnel) without needing to configure firewalls or port forwarding

In-Game Menu (Pause System)

• Any player can pause the game during a race
• A banner is broadcast to all players showing who paused, resumed, or quit
• The pause overlay does not interrupt the animation loop; requestAnimationFrame continues unaffected
• Settings are accessible from the pause menu with volume sliders for music and sound effects
• Restart Match Voting: any player can call a vote to restart; the vote passes if more than 50% of connected players agree within 15 seconds

Timer and Scoreboard

• A match timer counts up from the moment the race starts
• All connected players see the same synchronized timer value
• The scoreboard HUD displays live positions, lap counts, and player nicknames in real time

Audio

• Background music in menus and during races, with separate volume controls
• Countdown audio synced to the pre-race countdown seconds
• Engine sound with pitch that rises and falls with vehicle speed
• Crash sound plays once on initial impact, not continuously
• Button click, boost, lap completion, game over, and oil spin-out effects

Visual Design

• Dark arcade aesthetic with a layered DOM track rendering system
• Overpass road intersections rendered using ascending CSS z-index layers
• Animated background with moving car sprites during menus
• Glassmorphism-style modal overlays
• Smooth CSS transitions throughout the UI

Asset Attributions

Vehicle Sprites

The 15 vehicle sprites used in the game are from the Free Racing Game Kit (PNG) asset pack. The assembled track background images were constructed from tiles and road segments included in the same asset pack.

Audio

• Menu music, race music, countdown audio, and engine noise were sourced and adapted for use in this project.
• The car crash sound effect is sourced from a free sound library under a free-to-use license (dragon-studio-car-crash-sound).
• Button click sound and synthesized UI effects were created using the Web Audio API oscillator synthesis pipeline within sound.js.

Fonts

No external web fonts are loaded. The terminal mode interface uses monospace system fonts to maintain the command-line aesthetic without any external dependencies.

12. License

This project is distributed under the ISC License.

Copyright 2024 VimVim Racing Contributors

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Contributing

This project was built as a collaborative course assignment by a three-person team:

• Mumen — Core game engine, DOM rendering pipeline, physics system, collision, game state machine, host orchestration
• Ville — Audio system, keyboard input manager, pause/resume modal, HUD, vehicle and item styling
• Rene — WebSocket networking, lobby join flow, nickname validation, relay server, in-game chat

If you are forking or extending this project, please review the architecture notes in Section 8 and keep feature modules decoupled through the EventBus system.