Kart Racing Simulator

Todo list condivisa per il progetto di Interactive Graphics.

Obiettivo: costruire una web app racing 3D in browser con Three.js, 3 veicoli, 3 piste, guida arcade, AI, collisioni, HUD/minimappa e documentazione finale.

GitHub Pages

Playable build: https://sapienzainteractivegraphicscourse.github.io/final-project-arancin/

Regole Di Lavoro

• Usare develop come branch di integrazione.
• Creare branch per feature, non per persona.
• Tenere main stabile per consegna/GitHub Pages.
• Prima di merge in develop, eseguire bun run build.

Stato Branch

• feature/vehicle-assets: import asset Porsche e Silvia.
• feature/project-skeleton: struttura cartelle iniziale.
• feature/project-skeleton: scena Three.js base.
• feature/procedural-kart: kart costruito da zero.
• feature/vehicle-loaders: loader Porsche/Silvia.
• feature/tracks: 3 piste principali.
• feature/race-systems: countdown, giri, checkpoint, time trial, finish screen, AI base e contromano.
• feature/hud-minimap: HUD e minimappa.
• fix/performance-polish: alleggerimento, loading veicoli, UI polish e ghost time trial.
• docs/project-report: relazione/manuale finale.

1. Project Skeleton

• Creare cartelle principali:
  • src/config/
  • src/scene/
  • src/vehicles/
  • src/tracks/
  • src/systems/
  • src/materials/
  • src/styles/
• Sostituire starter Vite in src/main.js.
• Creare entry point applicativo pulito.
• Creare renderer Three.js con antialias.
• Abilitare shadow map.
• Impostare output color space sRGB.
• Creare scena base.
• Creare camera prospettica.
• Creare luci base:
  • ambient light;
  • directional light con shadow.
• Creare ground temporaneo.
• Gestire resize finestra.
• Creare game loop base con THREE.Timer.
• Limitare deltaTime a 0.05.
• Creare overlay UI minimale.
• Creare GUI setup placeholder.
• Esporre stato selezionato:
  • trackId;
  • vehicleId;
  • raceMode.
• Creare AppState condiviso:
  • fase setup;
  • fase loading;
  • fase preview;
  • fase race.
• Caricare preview Three.js solo dopo Start.
• Creare src/tracks/trackFactory.js placeholder.
• Creare src/vehicles/vehicleFactory.js placeholder.
• Far usare alla preview le factory placeholder invece di mesh dirette.
• Aggiungere docs/contracts.md con API condivise.
• Aggiungere script verify:scene.
• Spostare CSS runtime in src/styles/.
• Aggiornare script dev e preview con --host 0.0.0.0.
• Aggiungere documentazione skeleton in docs/project-skeleton.md.
• Verificare bun run build.

2. Veicoli

Interfaccia Comune

• Definire interfaccia/base class veicolo.
• Ogni veicolo deve esporre:
  • group;
  • performance;
  • setTransform(position, heading);
  • update(deltaTime, state);
  • setBodyColor(color);
  • setHeadlights(enabled);
  • toggleHeadlights();
  • dispose().
• Creare vehicleFactory.
• Separare dati performance da logica fisica.
• Ordinare velocita massime: Porsche > Silvia > Kart.

Kart Procedurale

• Costruire kart da zero con primitive Three.js.
• Creare gerarchia:
  • root group;
  • telaio;
  • carrozzeria;
  • sedile;
  • volante;
  • pilota opzionale;
  • assi;
  • quattro ruote;
  • fari.
• Ruote anteriori sterzanti con pivot separati.
• Ruote animate in base a distanza percorsa.
• Colore carrozzeria modificabile.
• Headlights toggle.
• Materiali con roughness/metalness coerenti.
• Piccole animazioni gerarchiche JS:
  • volante;
  • ruote;
  • possibile oscillazione telaio/sospensioni.

Porsche

• Importare asset GLB.
• Creare loader dedicato.
• Usare cache del modello caricato.
• Clonare modello per player e AI.
• Verificare scala.
• Verificare orientamento.
• Verificare origine/pivot.
• Correggere luci anteriori.
• Identificare o ricreare ruote animate.
• Applicare colore carrozzeria se possibile.
• Documentare fonte/licenza asset.

Nissan Silvia

• Importare asset FBX.
• Creare loader dedicato.
• Usare cache del modello caricato.
• Clonare modello per player e AI.
• Verificare scala.
• Verificare orientamento.
• Verificare origine/pivot.
• Correggere luci anteriori.
• Identificare o ricreare ruote animate.
• Applicare colore carrozzeria se possibile.
• Documentare fonte/licenza asset.

3. Fisica E Input

• Creare documentazione docs/physics-input.md.
• Creare InputManager.
• Gestire tasti tenuti premuti:
  • W / freccia su;
  • S / freccia giu;
  • A / freccia sinistra;
  • D / freccia destra;
  • Space handbrake.
• Gestire tasti one-shot:
  • C cambio camera;
  • L luci;
  • R restart.
  • Esc pausa/menu.
• Consumare one-shot una sola volta per frame.
• Bloccare scroll pagina per i tasti di gioco.
• Aggiungere dispose() a InputManager.
• Creare ArcadeVehicleController.
• Accettare vehicle.performance dal veicolo selezionato.
• Accettare track.spawn dalla pista selezionata.
• Stato fisico:
  • position;
  • heading;
  • speed;
  • steering;
  • boostTimer;
  • surfaceGrip;
  • surfaceType.
• Implementare reset(spawn).
• Implementare setPerformance(performance).
• Accelerazione/freno/retromarcia.
• Sterzo dipendente da velocita e grip.
• Ritorno graduale dello sterzo a zero.
• Attrito differenziato.
• Handbrake.
• Supporto placeholder per off-road/sabbia/erba tramite environmentState.
• Supporto placeholder per boost tramite environmentState.
• Calcolare distanceThisFrame per animazione ruote.
• Calcolare speedRatio.
• Collegare controller alla preview.
• Applicare vehicle.setTransform(state.position, state.heading).
• Passare stato fisico a vehicle.update(deltaTime, state).
• Implementare reset con R nella preview.
• Aggiornare docs/contracts.md con contratti input/controller.
• Verificare bun run build.

4. Piste

Sistema Tracciati

• Definire dati pista separati dalla generazione.
• Usare THREE.CatmullRomCurve3 chiuse.
• Generare road mesh campionando spline.
• Creare UV strada.
• Creare materiali strada/terreno.
• Salvare centerline.
• Salvare minimap bounds.
• Salvare checkpoint.
• Salvare boost pads.
• Salvare barrier colliders.
• Creare trackFactory.

Vegas Neon

• Layout non ovale.
• Curve a destra e sinistra.
• Chicane.
• Rettilineo veloce.
• Tema notturno.
• Neon rosa/cyan/giallo/verde.
• Tunnel colorati.
• Palazzi laterali.
• Bordi strada luminosi.
• Luci coerenti con notte.

Tropical Beach

• Layout non ovale.
• Curve a destra e sinistra.
• S veloci/chicane.
• Tornante o curva lenta.
• Sabbia e mare.
• Palme e props tropicali.
• Cielo diurno.
• Particelle sabbia in off-road.

Monaco Formula 1

• Layout cittadino stretto.
• Curve lente a 90 gradi.
• Chicane.
• Tornante.
• Rettilineo breve.
• Barriere vicine.
• Props urbani/eleganti.
• Look tecnico da pista cittadina.

5. Collisioni

• Documentare docs/collisions.md.

Track Interaction System

• Creare TrackInteractionSystem.
• Sostituire environmentState hardcoded nella scena.
• Gestire default robusti se la pista non espone dati completi.
• Aggiornare docs/contracts.md.

Off-road

• Rilevamento off-road tramite centerline e roadHalfWidth.
• Ridurre surfaceGrip fuori strada.
• Ridurre speedLimitMultiplier fuori strada.
• Esporre surfaceType per HUD futuro.

Boost Pad

• Rilevamento boost pad.
• Applicare boostFactor.
• Cooldown breve boost.
• Annullare boost su impatto importante.

Barriere

• Collisione player-barriere.
• Test punto/veicolo contro collider oriented box 2D.
• Applicare correzione fisica ogni frame di intersezione.
• Cooldown solo per audio/penalita, non per risposta fisica.
• Spingere fuori dalla barriera lungo la normale.
• Ridurre/invertire velocita su impatto frontale.

Player Vs AI

• Collisione player-bot.
• Separare posizioni player/bot.
• Penalita o feedback collisione.

6. Gara E AI

Modalita

• Documentare docs/race-systems.md.
• Supportare modalita race:
  • gara contro AI;
  • giri multipli;
  • checkpoint in ordine;
  • classifica semplice player predisposta.
• Supportare modalita time-trial:
  • solo player;
  • giro veloce;
  • cronometro;
  • best lap locale.

Race Manager

• Creare RaceManager.
• Definire fasi:
  • idle;
  • countdown;
  • running;
  • finished.
• Configurare totalLaps in base alla modalita:
  • race: 3 giri;
  • time-trial: 1 giro.
• Implementare startCountdown().
• Implementare startRace().
• Implementare reset().
• Implementare update(deltaTime, playerState, trackInfo).
• Esportare getState().
• Non rompersi con trackInfo.checkpoints = [].

Countdown E Start Flow

• Countdown iniziale.
• Bloccare movimento durante countdown.
• Mostrare countdown in UI/overlay.
• Passare a gara running dopo GO.
• Menu pausa con Esc.
• Ritorno alla GUI iniziale dal menu pausa.

Tempi E Giri

• Cronometro totale.
• Cronometro giro.
• Checkpoint in ordine predisposti.
• Evidenziare checkpoint successivo.
• Giri.
• Best lap predisposto per time trial.
• Finish screen con classifica lap time.
• Storico lap completati in localStorage.
• Restart gara.

AI E Race Mode

• Predisporre stato aiEnabled.
• Esporre posizione semplice player.
• Aggiornare posizione player rispetto all'AI.
• Preparare controller logico AI su centerline.
• AI opponent visibile.
• AI usa stesso veicolo selezionato dal player.
• Velocita AI dipendente dal veicolo.
• AI frena prima delle curve.
• AI accelera in uscita.
• AI segue traiettoria con offset laterale.
• AI competitiva ma battibile in tuning finale dedicato.

Contromano

• Avviso contromano:
  • progresso piu vicino su centerline;
  • heading pista da lookahead;
  • prodotto scalare con forward veicolo;
  • soglia temporale per evitare falsi positivi.

Contratti E Verifiche

• Aggiornare docs/contracts.md con contratto RaceManager.
• Aggiornare docs/contracts.md con contratto checkpoint.
• Aggiornare verify:scene se il countdown ha DOM stabile.
• Verificare bun run build.

7. Camera

• Documentare docs/camera-system.md.

Camera Controller

• Creare CameraController.
• Estrarre follow camera da startScenePreview.js.
• Mantenere comportamento follow attuale.
• Gestire resize camera nel controller.
• Aggiornare docs/contracts.md.

Modalita Camera

• Follow camera dietro il veicolo.
• Top/debug camera.
• Driver/hood camera opzionale.
• Free/orbit camera opzionale.
• Cambio camera con C.

Feedback

• Camera shake leggero su collisione.
• Evitare shake fastidioso in modalita debug/top.

8. HUD, UI E Minimap

• Menu selezione pista.
• Menu selezione veicolo.
• Selezione colore veicolo.
• Pulsante start.
• HUD speed.
• HUD lap.
• HUD time.
• HUD checkpoint.
• HUD countdown/wrong way overlay.
• HUD posizione/gap.
• Minimap canvas.
• Disegnare centerline su minimap.
• Marker player.
• Marker AI.
• Marker checkpoint/start.
• UI responsive.
• Evitare testo sovrapposto su mobile.

9. Audio

• Web Audio API.
• Motore continuo non invasivo.
• Volume master basso.
• Audio abilitato solo dopo gesto utente.
• Suono checkpoint.
• Suono countdown.
• Suono collisione.
• Suono boost.
• Toggle audio.

10. Ambiente E Animazioni

• Skybox/colore cielo per tema.
• Luci diverse per tema.
• Nuvole animate.
• Spalti appoggiati al terreno.
• Bandiere animate.
• Pubblico/props leggeri.
• Particelle:
  • sabbia;
  • boost;
  • collisione/scintille leggere.
• Texture procedurali:
  • color map;
  • normal map;
  • roughness/specular map dove utile.
• Almeno uno shader/materiale custom se utile e spiegabile.

11. Verifica

• bun run build passa.
• Dev server avviabile.
• Preview avviabile.
• Script verify:scene con Playwright.
• Verifica canvas non vuoto.
• Verifica nessun errore console grave.
• Verifica desktop.
• Verifica mobile.
• Verifica asset caricati.
• Verifica FPS accettabile.

12. Documentazione Finale

• README finale con:
  • descrizione progetto;
  • comandi install/build/run;
  • link GitHub Pages;
  • controlli;
  • feature principali.
• Relazione/manuale 5-10 pagine.
• Ambiente usato.
• Librerie usate.
• Asset esterni e licenze.
• Modelli gerarchici.
• Texture e materiali.
• Luci.
• Animazioni JS.
• Interazioni utente.
• AI e collisioni.
• Limitazioni note.
• Screenshot finali.

13. Performance, Polish E Ghost

• Documentare docs/performance-polish.md.
• Alleggerire mappe pesanti senza cambiare gameplay.
• Aggiungere FPS in HUD per confrontare gli scatti tra piste.
• Aggiungere toggle diagnostici F1-F4 per minimap, ombre, props e renderer info.
• Eliminare flash del placeholder su Porsche/Silvia.
• Indagare caricamento e tempo minimo overlay dei veicoli importati.
• Migliorare leggibilita HUD, tempi e testi runtime.
• Unificare HUD sinistra/destra in un pannello runtime piu pulito.
• Alzare menu setup riducendo margine verticale senza ridurre il logo.
• Correggere avanzamento checkpoint iniziale sul traguardo.
• Aggiungere ghost del best lap in time trial.
  • Storage/versioning dati ghost.
  • Recorder campioni giro valido.
  • Rendering veicolo ghost semi-trasparente.
  • Interpolazione ghost sul tempo giro corrente.