Panoramica

Per aiutare gli sviluppatori a capire come si usa l'API di Steamworks, abbiamo incluso il codice sorgente di una versione perfettamente funzionante del classico gioco di azione multigiocatore Spacewar!. Si tratta di un semplice gioco 2D con supporto fino a 4 giocatori che fornisce un'opportunità perfetta per mettere in mostra molte delle API disponibili nell'SDK di Steamworks.

Mentre studi il codice ricorda che il nostro scopo era quello di scrivere un gioco semplice e basilare, in modo da mostrare l'API di Steamworks nella maniera più chiara possibile. Non troverai nuove, fantastiche tecnologie grafiche, ma esempi chiari su come integrare profondamente le funzionalità di Steamworks nei tuoi progetti.

Le funzionalità delle API e di Steamworks dimostrate in questo codice includono:

• Cloud
  
• Integrazione con la Comunità (avatar, nomi degli amici, ecc.)
  
• Segnalazione dei crash
  
• Amici
  
• Superficie HTML
  
• Inventario
  
• Classifiche
  
• Matchmaking (sia lobby che lista dei server)
  
• Autenticazione multigiocatore (4 giocatori supportati nel gioco)
  
• Funzionalità di rete
  
• Statistiche e achievement
  
• Chat vocale

Sviluppo ed esecuzione dell'esempio

Requisiti:

• Visual Studio 2005 o più recente.
  
• SDK DirectX
  
• SDK di Steamworks. Scarica quila versione più recente.

Dopo aver scaricato ed estratto il pacchetto dell'SDK di Steamworks, trova la directory secondaria SteamworksExample. Dentro questa directory troverai SteamworksExample.sln, che può essere aperto con Visual Studio. Apri la soluzione e compila il progetto. Se la compilazione ha esito positivo, sei pronto per iniziare e puoi eseguire il progetto direttamente da Visual Studio (Steam dovrà essere in esecuzione in background). Se la build o l'esecuzione falliscono, prova uno dei seguenti suggerimenti.

Problemi comuni della build

• Impossibile aprire il file di inclusione: 'd3d9.h'
  Questo errore significa che la directory di inclusione del tuo sistema non include il percorso di inclusione di D3D, o che non hai installato l'SDK di D3D. Innanzitutto, assicurati di aver scaricato e installato l'SDK di DirectX Una volta che l'SDK è installato devi configurare il percorso di inclusione. Puoi farlo per l'intero sistema attraverso le variabili standard dell'ambiente di Visual Studio, oppure solo per il progetto SteamworksExample modificandone le proprietà.
  
• Errore fatale LNK1104: impossibile aprire il file 'd3d9.lib'
  Questo errore significa che il percorso della libreria del tuo sistema non include la directory della libreria D3D. Vedi le istruzioni sopra, ma al posto del percorso di inclusione dovrai aggiornare quello della libreria.
  
• Steam deve essere in esecuzione per giocare questo gioco. La chiamata (SteamAPI_Init non è riuscita).
  Questo errore significa che Steam non è in esecuzione. Se Steam è in esecuzione, assicurati che nella directory dell'eseguibile del gioco sia presente il file steam_appid.txt. Questo file è incluso con l'esempio dell'SDK e dovrebbe essere presente se esegui il programma da Visual Studio o direttamente dalle directory secondarie Debug o Release.
  
  Quando lanci il gioco direttamente dall'eseguibile e non dall'interfaccia di Steam, questo file deve essere presente e deve contenere una singola riga con l'appID del gioco (Valve assegnerà un appID a ciascuno dei tuoi giochi, l'appID dell'esempio è 480). Quando distribuisci il tuo gioco tramite Steam questo file non servirà, dato che Steam rileverà automaticamente il tuo appID al momento in cui il gioco viene lanciato.
  
• Impossibile avviare l'applicazione perché il file steam_api.dll non è stato trovato. Reinstallare l'applicazione potrebbe risolvere questo problema.
  Per eseguire con successo il programma, steam_api.dll deve trovarsi nella stessa directory dell'eseguibile del gioco di esempio. Vale anche per i tuoi giochi che fanno uso di Steamworks. Il file del progetto di Visual Studio dovrebbe posizionare l'eseguibile nella directory corretta al momento della compilazione, ma se stai usando un compilatore diverso o hai modificato la soluzione o i file del progetto, potresti doverlo copiare manualmente. Puoi redistribuire steam_api.dll con i tuoi giochi di Steamworks quando li distribuisci.
  
• Impossibile avviare l'applicazione perché d3dx_??.dll non è stato trovato. Reinstallare l'applicazione potrebbe risolvere questo problema.
  L'esempio fa affidamento sulla libreria di supporto di D3D9X, inclusa con l'SDK di DirectX. Se lanci l'esempio sullo stesso computer su cui l'hai compilato nella libreria, dovrebbe essere trovato automaticamente. Se i file binari compilati sono stati copiati su un altro computer, potresti dover reinstallare i ridistribuibili D3D per ottenere la stessa versione di D3D9X che hai usato per la compilazione sul tuo computer di sviluppo.

Panoramica del codice

Una volta che il progetto di esempio Spacewar! sarà compilato e in esecuzione, vorrai iniziare a guardarne il codice. Cercando i file all'interno del sistema di ricerca di Visual Studio vedrai che il codice è stato diviso in codice di gioco e codice del motore. Puoi ignorare il codice nella cartella del motore. Supporta il rendering basico in 2D attraverso D3D e input basilari tramite tastiera. Tutte le componenti del codice che documentano l'utilizzo dell'API di Steamworks si trovano nella cartella Game.

Le parti più interessanti per iniziare ad analizzare il codice sono descritte brevemente qui sotto:

• Main.cpp -- Punto di ingresso principale per il gioco di esempio.
  Utilizzo dell'API dimostrato:
  
  • Avvio dell'API del client -- Dovrai avviare l'API durante le fasi iniziali di avvio dell'app. Potrai vedere come avviene questo processo all'interno della funzione RealMain() in Main.cpp.
    
  • Registro degli errori/avvisi dell'API -- Durante lo sviluppo, potresti volere ottenere dei registri di output dall'API di Steam in modo da aiutare con il debug dei problemi. Puoi vedere un esempio di come impostare la registrazione per il debug all'interno della funzione RealMain(), dove viene chiamata ISteamClient::SetWarningMessageHook.
    
  • Segnalazione dei crash -- Per il tuo gioco, potresti volere usare lo strumento di segnalazione dei crash attraverso mini-dump incluso in Steam. Troverai un esempio dell'installazione dell'handler delle eccezioni e dell'impostazione della scrittura di mini-dump su WinMain() e su MiniDumpFunction(), all'interno di Main.cpp.
    
• SpaceWarServer.cpp/h -- Codice per i server per il gioco di esempio.
  Utilizzo dell'API dimostrato:
  
  • Inizializzazione dell'API dei server di gioco -- All'interno dei server di gioco, vorrai avviare una versione basilare dell'API che non espone le interfacce dei singoli utenti. Troverai un esempio nel costruttore per CSpaceWarServer in SpaceWarServer.cpp.
    
  • Esecuzione di callback API -- Nei tuoi giochi vorrai effettuare periodicamente delle callback di Steam per processare i risultati delle chiamate asincrone all'API da parte di Steam. Nella funzione CSpaceWarServer::RunFrame() troverai un esempio sull'esecuzione delle callback su un server di gioco attraverso SteamGameServer_RunCallbacks. Troverai anche esempi di come gestire le callback individuali e registrarle all'interno del codice di costruzione e file di intestazione CSpaceWarServer.
    
  • Autenticazione multigiocatore (gestione dei ban del VAC) -- Se il tuo è un gioco multigiocatore online, vorrai avere conferma che gli utenti siano in possesso del gioco, prima che si connettano a un server online. All'interno di SpaceWarServer.cpp troverai gli handler delle callback e le chiamate all'API ISteamGameServer con questo scopo. Vedrai anche come gestire risposte negative ed espulsioni che Steam potrebbe inviarti nel caso che gli utenti non siano in possesso del tuo gioco, siano stati banditi o dovrebbero essere espulsi per avere utilizzato trucchi.
    
  • API di rete -- Se stai sviluppando un gioco online, potresti volere utilizzare le API di rete incluse con Steam. Troverai esempi del loro uso sul lato server attraverso chiamate all'API ISteamNetworking utilizzando la funzione accessoria SteamGameServerNetworking() e le callback all'interno di SpaceWarServer.cpp.
    
  • Matchmaking e comunicazione con il server master -- Se stai sviluppando un gioco multigiocatore e desideri utilizzare il browser dei server di Steam, il tuo server di gioco dovrà comunicare con i server master di Steam. Troverai esempi di questa funzionalità nel costruttore CSpaceWarServer e nel metodo CSpaceWarServer::SendUpdatedServerDetailsToSteam().
    
• SpaceWarClient.cpp/h -- Codice del lato client per il gioco di esempio.
  Utilizzo dell'API dimostrato:
  
  • Matchmaking attraverso le lobby -- Nei tuoi giochi online, potresti volere includere il matchmaking tramite lobby in aggiunta a, o invece di, quello tramite ricerca dei server. Troverai esempi di utilizzo del codice per le lobby e le callback attraverso l'interfaccia ISteamMatchmaking all'interno di SpaceWarClient.cpp. Consulta anche Lobby.cpp/h, che include parti del codice che gestiscono lo stato e le callback una volta che si è all'interno di una data lobby.
    
  • Integrazione degli amici e della Comunità -- Steam ti consente di usare all'interno del tuo gioco informazioni sull'identità dei giocatori, tra cui il loro alias e il loro avatar personale. Troverai un esempio di integrazione degli alias e degli avatar nelle classifiche attraverso l'interfaccia ISteamFriends all'interno di SpaceWarClient.cpp
    
  • API di rete -- Troverai un esempio di utilizzo dal lato client dell'API di rete di Steam all'interno di SpaceWarClient.cpp (vedi SpaceWarServer.cpp per l'implementazione sul lato server).
    
• StatsAndAchievements.cpp/h -- Gestione delle statistiche e degli achievement per il gioco di esempio.
  Utilizzo dell'API dimostrato:
  
  • Statistiche e achievement -- Troverai un'implementazione della gestione delle statistiche e degli achievement all'interno di StatsAndAchievements.cpp. Il file contiene la classe CStatsAndAchievements, che viene chiamata da CSpaceWarClient con informazioni aggiornate sullo stato. Quando CStatsAndAchievements riceve informazioni su un cambiamento di stato dal client di gioco, gestisce la notifica a Steam dei cambiamenti alle statistiche e gli achievement dell'utente attraverso l'interfaccia ISteamUserStats.
    
• Lobby.cpp/h -- Matchmaking attraverso le lobby
  Utilizzo dell'API dimostrato:
  
  • Matchmaking tramite lobby -- Troverai parte dell'implementazione del matchmaking tramite le lobby nel gioco di esempio in Lobby.cpp. Lobby.cpp funziona insieme a SpaceWarClient.cpp per gestire il matchmaking, quindi consulta entrambe le funzioni. Quando esamini il codice per le lobby, presta particolare alle callback e alle chiamate ai metodi dell'interfaccia ISteamMatchmaking.
    
• ServerBrowser.cpp/h -- Ricerca di server in gioco
  Utilizzo dell'API dimostrato:
  
  • Matchmaking tramite lista dei server -- Se il tuo sistema di matchmaking utilizza la lista dei server, ti consigliamo di fornire un elenco di server direttamente all'interno del gioco, da affiancare la lista fornita dall'interfaccia di Steam. Troverai un esempio di come ottenere la lista di server online per il tuo gioco e di come mostrarla al giocatore all'interno di ServerBrowser.cpp.
    
• Inventory.cpp/h -- Servizio dell'inventario di Steam
  Utilizzo dell'API dimostrato:
  
  • Steam Inventory -- Si integra con l'inventario di Steam, il quale fornisce accesso all'economia di Steam. Ciò ti consente di integrare facilmente oggetti all'interno del tuo gioco.
    

Se il tuo gioco è già dotato di un motore per l'autenticazione e il matchmaking che vuoi continuare a utilizzare, potresti volere rimuovere la definizione USE_GS_AUTH_API da Spacewars.h. Una volta rimossa, l'esempio NON userà l'autenticazione e il matchmaking di Steam, ma sarai ancora in grado di accedere ad altre funzionalità di Steam come gli achievement e le informazioni sugli amici. Consulta il codice per i dettagli.