Core

Panoramica del core

Il core è lo strato comune usato dai progetti agpunicas. Gestisce il ciclo dell'applicazione e i servizi generali, lasciando ai singoli giochi la definizione di fisica, collisioni, intelligenza artificiale e regole.

Responsabilità principali

Area	Classi principali	Scopo
Applicazione	Game, Window	Avvio SDL, game loop, eventi, stack delle scene e presentazione dei frame.
Scena di gioco	Scene, GameScene, Object	Contenimento, aggiornamento e query sugli oggetti.
Interfaccia	UIScene, OverlayScene	Menu, HUD, overlay e parallax.
Rendering	View, RenderableObject	Camera, viewport, culling, ordinamento per layer e disegno.
Immagini	Sprite e derivate	Texture, animazioni, composizione a tile, riempimenti e testo.
Query spaziali	Quadtree	Riduzione degli oggetti da esaminare per rendering e query geometriche.
Servizi	Audio, Fonts, Scheduler, Singleton	Risorse condivise e azioni differite.
Livelli	LevelData	Lettura, validazione e salvataggio JSON, conversioni geometriche condivise da loader ed editor.
Strumenti	EditorScene, EditorUI, EditableObject	Editor visuale e persistenza JSON dei livelli.
Post-processing	CPUShaderWindow, GPUShaderWindow	Effetti applicati al frame completo.

Il diagramma completo delle classi è disponibile in una pagina dedicata, raggiungibile anche dal menu laterale.

Relazioni essenziali

flowchart TD
    Game --> Window
    Game --> SceneStack[Stack di Scene]
    SceneStack --> Scene
    Scene --> View
    Scene --> Object
    Object --> RenderableObject
    RenderableObject --> Sprite
    Scene --> Scheduler
    GameScene --> Quadtree
    GameScene --> OverlayScene

Loading

La distinzione più importante è questa:

• una Scene decide quali oggetti esistono e vengono aggiornati;
• una View decide quale parte della scena viene mostrata;
• un RenderableObject descrive dove e con quali proprietà disegnare;
• uno Sprite descrive quale immagine usare e come campionarla.

Game non disegna direttamente gli oggetti: consegna le scene alla Window. È View::render() che cerca gli oggetti nell'area visibile, li ordina per layer e chiama draw() sui RenderableObject. Per la logica accade l'inverso: Game passa il tempo trascorso alle scene, che aggiornano gli oggetti secondo il proprio modello temporale.

Dal progetto al primo frame

Nei quattro esempi, main() crea e registra una sottoclasse di Game, chiama init() e infine run(). Il costruttore del gioco concreto inizializza i servizi dopo che la classe base ha creato finestra e renderer; init() costruisce le scene. Alla chiusura il main distrugge il gioco, che libera scene e servizi prima della finestra, poi chiama SDL_Quit(). Un oggetto creato con una Scene* si registra automaticamente nella scena; questa lo trasferisce nel proprio contenitore all'aggiornamento successivo.

L'ordine di studio suggerito è: Game, eventi, Scene e Object, View, Sprite. In seguito affronta overlay e UI, quadtree e risorse.

Dipendenze

Il core usa:

• SDL3 per finestra, eventi e rendering;
• SDL3_image per le immagini;
• SDL3_mixer per suoni e musica;
• SDL3_ttf, opzionale, per il testo;
• SDL_GPU (SDL3 3.4 o successiva), per GPUShaderWindow quando è attivo WITH_SHADERS.

Le opzioni CMake WITH_TTF e WITH_SHADERS abilitano i moduli opzionali. Il core viene compilato come libreria statica agpcore e collegato dal progetto finale.

Cosa appartiene ai progetti

Il core non conosce concetti come Mario, Link, Box2D, gravità, vita o nemici. Queste idee appartengono ai progetti concreti, che specializzano Game, GameScene, Object e RenderableObject oppure costruiscono classi nuove sopra di esse.

Le SpriteFactory e i LevelLoader presenti nei progetti sono esempi di questo livello applicativo: non sono classi del core. Per aggiungere una nuova entità o schermata, segui la guida all'estensione.

LevelData appartiene invece al core: condivide formato, validazione e conversioni geometriche senza conoscere le classi dei giochi. La creazione delle entità resta nei LevelLoader. Vedi LevelData e livelli JSON.

Sorgenti di riferimento

• core/LevelData.h
• core/CMakeLists.txt
• core/Game.h
• core/Scene.h
• core/Object.h