Questa API può essere utilizzata per pubblicizzare in maniera selettiva la tua sessione di gioco multigiocatore in una chat di gruppo di Steam. Informa Steam del numero di posti disponibili per i giocatori nel tuo gruppo, fornendo loro una stringa di accesso che segnalerà la possibilità per quel numero di utenti di accedere al gruppo seguendo il "segnale". Regola il numero di posti aperti se altri giocatori accedono attraverso altri metodi di matchmaking.

Ad esempio, puoi usare ISteamParties insieme a una lobby privata. Crea una lobby privata e poi usa ISteamParties::CreateBeacon per creare un "segnale" per il gruppo per il numero di giocatori desiderato. La stringa di connessione al gioco dovrebbe indicare l'ID della lobby privata.

Il segnale apparirà nella sezione specificata di Steam (ad esempio nella chat di gruppo) e attraverso l'API in gioco ISteamParties, come descritto in basso. Steam "prenota" degli slot per il numero di giocatori desiderati. Quando un utente segue il segnale, Steam conserverà uno slot prenotato e lancerà il gioco usando la stringa di connessione fornita.

La sessione di gioco che ha creato il segnale verrà informata di questa prenotazione, così che il gioco possa mostrare la corretta stringa "L'utente <username> si sta unendo al tuo gruppo", o altri indicatori. Una volta che l'utente si sarà unito con successo, la sessione di gioco dovrebbe chiamare ISteamParties::OnReservationCompleted per dire a Steam che l'utente si è unito con successo, altrimenti la prenotazione scadrà e lo slot verrà riaperto.

Quando tutti gli slot del segnale saranno occupati (attraverso prenotazioni per utenti che stanno lanciando il gioco o utenti che fanno già parte del gruppo), Steam lo nasconderà e lo disattiverà.

Per annullare il segnale, ad esempio quando il gruppo è pieno e il gioco sta iniziando, chiama ISteamParties::DestroyBeacon.

Il lato client di questa operazione (vedere e seguire segnali) può essere gestito anche dal tuo gioco. Usando ISteamParties::GetNumActiveBeacons e ISteamParties::GetBeaconDetails, il tuo gioco può ottenere una lista di segnali da altri utenti al momento attivi in sezioni rilevanti per l'utente corrente. Se l'utente lo desidera, chiama ISteamParties::JoinParty per "seguire" uno di quei segnali.

Funzioni membro

Le funzioni membro per ISteamParties vengono chiamate tramite la funzione globale di accesso SteamParties(), che viene fornita dal file di intestazione steam/ISteamMatchmaking.h.

GetNumAvailableBeaconLocations

Nome	Tipo	Descrizione
puNumLocations	uint32*	Indirizzo della variabile per cui ricevere il numero di risposta.

Ottiene il numero di sezioni in cui sei in grado di pubblicare un segnale di gruppo.

Usa questa funzione per dare una dimensione alla lista dei risultati di una chiamata a ISteamParties::GetAvailableBeaconLocations.

Restituisce: bool

GetAvailableBeaconLocations

Nome	Tipo	Descrizione
pLocationList	SteamPartyBeaconLocation_t*	Lista risultante di sezioni disponibili per il segnale.
uMaxNumLocations	uint32	Il numero massimo di voci da includere nella lista di cui sopra. Dovrebbe essere >= il risultato di GetNumAvailableBeaconLocations.

Ottiene la lista di sezioni in cui puoi pubblicare un segnale di gruppo.

Vedi anche: ISteamParties::GetNumAvailableBeaconLocations

Restituisce: bool

CreateBeacon

Nome	Tipo	Descrizione
unOpenSlots	uint32	Numero di slot di prenotazione da creare per il segnale. Di solito, è la dimensione desiderata per il tuo gruppo meno uno (l'utente corrente).
pBeaconLocation	SteamPartyBeaconLocation_t*	Informazioni sulla sezione per il segnale. Dovrebbe essere una delle sezioni restituite da ISteamParties::GetAvailableBeaconLocations.
pchConnectString	char *	Stringa di connessione che sarà data al gioco al momento del lancio per un utente che segue il segnale.
pchMetadata	char *	Metadati di gioco addizionali che possono essere imposti sul segnale e che vengono esposti tramite ISteamParties::GetBeaconDetails.

Crea un segnale. Puoi crearne solo una alla volta. Steam mostrerà il segnale nella sezione specificata e consentirà al numero massimo di utenti indicato da unOpenSlots di "seguire" il segnale del tuo gruppo.

Se gli utenti si uniscono al tuo gruppo attraverso un altro tipo di matchmaking, regola il numero di slot disponibili usando ISteamParties::ChangeNumOpenSlots.

Restituisce: SteamAPICall_t da utilizzare con un risultato della chiamata a CreateBeaconCallback_t.
Restituisce k_uAPICallInvalid se il processo ha già un segnale attivo o se le informazioni sulla sezione non sono valide.

OnReservationCompleted

Nome	Tipo	Descrizione
ulBeacon	PartyBeaconID_t	L'ID del segnale creato dal tuo processo.
steamIDUser	CSteamID	L'ID di Steam dell'utente che si sta unendo al tuo gruppo.

Quando un utente segue il tuo segnale, Steam prenoterà per lui uno degli slot del gruppo aperti e invierà al tuo gioco una callback ReservationNotificationCallback_t. Quando quell'utente si unisce al tuo gruppo, chiama OnReservationCompleted per notificare Steam che l'utente si è unito con successo.

ChangeNumOpenSlots

Nome	Tipo	Descrizione
ulBeacon	PartyBeaconID_t	L'ID del segnale creato dal tuo processo.
unOpenSlots	uint32	Il nuovo numero di slot aperti nel tuo gruppo.

Se un utente si unisce al tuo gruppo attraverso un'altro metodo di matchmaking (ad esempio un invito diretto da un amico di Steam o dal tuo stesso sistema di matchmaking), il tuo gioco dovrebbe ridurre il numero di slot aperti che Steam sta gestendo attraverso il segnale di gruppo. Ad esempio, se hai creato il segnale con cinque slot e Steam ti ha inviato due callback ReservationNotificationCallback_t, se un terzo utente si è unito direttamente dovrai chiamare ChangeNumOpenSlots con un valore di 2 per unOpenSlots. Quel valore rappresenta il numero totale di nuovi utenti che desideri siano inviati da Steam al tuo gruppo.

Restituisce: SteamAPICall_t da usare con un risultato della chiamata a ChangeNumOpenSlotsCallback_t.
Restituisce k_uAPICallInvalid se l'ID del segnale non è valido.

DestroyBeacon

Nome	Tipo	Descrizione
ulBeacon	PartyBeaconID_t	L'ID del segnale da eliminare.

Chiama questo metodo per eliminare il segnale del gruppo di Steam. Farà immediatamente sì che Steam smetta di mostrare il segnale nella sezione specificata. Nota: utenti che sono già nella fase di unione potrebbero arrivare nel tuo gruppo aspettandosi di unirsi.

Il tuo gioco dovrebbe chiamare questo metodo quando il gruppo è pieno e il gioco sta iniziando, oppure quando l'utente ha deciso di abbandonare il processo di creazione di una lobby. Il segnale verrà eliminato automaticamente quando il tuo gioco si arresta, ma il comportamento consigliato è che il gioco chiami DestroyBeacon al momento giusto.

Restituisce: bool

GetNumActiveBeacons

Questo metodo non ha parametri.

Ottiene il numero di segnali di gruppo attivi creati da altri utenti per il tuo gioco che sono visibili dall'utente corrente.

Restituisce: uint32

GetBeaconByIndex

Nome	Tipo	Descrizione
unIndex	uint32	Indice del segnale.

Da usare con ISteamParties::GetNumActiveBeacons per l'iterazione dei segnali attivi visibili dall'utente corrente. unIndex è un indice basato su zero, quindi esegui l'iterazione nell'intervallo [0, GetNumActiveBeacons() - 1]. Viene restituito PartyBeaconID_t, che può essere usato con ISteamParties::GetBeaconDetails per ottenere informazioni sui segnali adatti a essere mostrati all'utente.

Restituisce: PartyBeaconID_t

GetBeaconDetails

Nome	Tipo	Descrizione
ulBeaconID	PartyBeaconID_t	ID del segnale da interrogare.
pSteamIDBeaconOwner	CSteamID*	Il creatore del segnale.
pLocation	SteamPartyBeaconLocation_t*	La sezione in cui è stato pubblicato il segnale.
pchMetadata	char*	Il buffer per ricevere eventuali metadati addizionali che il gioco ha impostato su questo segnale (ad esempio la modalità di gioco). Sarà NULL quando arrestato con successo.
cchMetadata	uint32	Le dimensioni del buffer di cui sopra.

Ottiene dettagli sul segnale specificato. Puoi usare l'API ISteamFriends per ottenere dettagli aggiuntivi su pSteamIDBeaconOwner e ISteamParties::GetBeaconLocationData per ottenere dettagli aggiuntivi su pLocation. I contenuti di pchMetadata sono specifici per il tuo gioco e, se presenti, saranno quelli impostati dal processo di gioco che ha creato il segnale.

Restituisce: bool

JoinParty

Nome	Tipo	Descrizione
ulBeacon	PartyBeaconID_t	L'ID del segnale del gruppo a cui vuoi unirti.

Quando l'utente indica che vuole unirsi al gruppo pubblicizzato dal segnale, chiama questo metodo. In caso di esito positivo, Steam prenoterà uno slot per questo utente nel gruppo e restituirà la stringa "unisciti al gioco" necessaria per il completamento della connessione.

Restituisce: SteamAPICall_t da usare con un risultato della chiamata a JoinParty_t.
Restituisce k_uAPICallInvalid se l'ID del segnale non è valido.

GetBeaconLocationData

Nome	Tipo	Descrizione
BeaconLocation	SteamPartyBeaconLocation_t	La sezione da interrogare.
eData	ESteamPartyBeaconLocationData	Il tipo di dati della sezione che vuoi ottenere.
pchDataStringOut	char *	Buffer di output per la stringa di dati sulla sezione. Sarà NULL quando arrestato con successo.
cchDataStringOut	int	Dimensioni del buffer indicato da pchDataStringOut.

Interroga i metadati generici per la sezione del segnale fornita. Ad esempio il nome, o l'URL per un'icona se il tipo di sezione le supporta (come l'icona per una chat di gruppo di Steam).

Restituisce: bool

Callback

Queste sono callback che possono essere attivate chiamando SteamAPI_RunCallbacks. Molte di esse saranno attivate direttamente in risposta alle funzioni membro di ISteamParties.

JoinPartyCallback_t

Questa callback è usata come una chiamata di risposta per ISteamParties::JoinParty. In caso di esito positivo, avrai uno slot riservato nel gruppo del proprietario del segnale e dovresti usare m_rgchConnectString per connetterti al suo gioco e completare il processo.

Nome	Tipo	Descrizione
m_eResult	EResult	Il risultato del tentativo di unirsi al gruppo.
m_ulBeaconID	PartyBeaconID_t	L'ID del segnale usato per il tentativo.
m_SteamIDBeaconOwner	CSteamID	Il creatore del segnale usato per il tentativo.
m_rgchConnectString	char[256]	In caso di esito positivo, una stringa "unisciti al gioco" che il tuo gioco può usare per completare il processo di unione al gruppo desiderato.

CreateBeaconCallback_t

Questa callback è usata come una chiamata di risposta per ISteamParties::CreateBeacon. In caso di esito positivo, il tuo segnale è stato pubblicato nella sezione desiderata e puoi iniziare a ricevere callback ISteamParties::ReservationNotificationCallback_t per gli utenti che lo seguono.

Nome	Tipo	Descrizione
m_eResult	EResult	Il risultato del tentativo di creare un segnale.
m_ulBeaconID	PartyBeaconID_t	L'ID del segnale appena creato.

ReservationNotificationCallback_t

Dopo aver creato un segnale, quando un utente lo "segue" Steam ti invierà questa callback per informarti che devi essere pronto per l'unione alla partita da parte dell'utente. Quando l'utente si è unito, assicurati di chiamare ISteamParties::OnReservationCompleted per farlo sapere a Steam.

Nome	Tipo	Descrizione
m_ulBeaconID	PartyBeaconID_t	L'ID del tuo segnale.
m_steamIDJoiner	CSteamID	L'ID di Steam dell'utente che sta seguendo il tuo segnale.

ChangeNumOpenSlotsCallback_t

Il risultato di chiamata per ISteamParties::ChangeNumOpenSlots.

Nome	Tipo	Descrizione
m_eResult	EResult	Il risultato del tentativo di cambiare il numero di slot aperti.

AvailableBeaconLocationsUpdated_t

Notifica che la lista di sezioni disponibili per la pubblicazione di un segnale è stata aggiornata.

Questa callback non ha membri.

ActiveBeaconsUpdated_t

Notifica che la lista di segnali attivi visibili dall'utente corrente è cambiata.

Questa callback non ha membri.

Strutture

Queste sono strutture che le funzioni all'interno di ISteamParties possono restituire o con cui possono interagire.

SteamPartyBeaconLocation_t

Nome	Tipo	Descrizione
m_eType	ESteamPartyBeaconLocationType	Il tipo di sezione.
m_ulLocationID	uint64	Identificatore opaco di questa sezione.

Enumerazioni

Queste sono le enumerazioni definite per l'utilizzo con ISteamParties.

ESteamPartyBeaconLocationType

I tipi di sezione in cui possono venire pubblicati i segnali.

Nome	Valore	Descrizione
k_ESteamPartyBeaconLocationType_Invalid	0	Tipo di sezione non valido.
k_ESteamPartyBeaconLocationType_ChatGroup	1	Una chat di gruppo di Steam.
k_ESteamPartyBeaconLocationType_Max		Il valore è sempre maggiore di uno rispetto al valore del tipo di sezione valido più grande.

ESteamPartyBeaconLocationData

I tipi di metadati estesi per le sezioni del segnale.

Nome	Valore	Descrizione
k_ESteamPartyBeaconLocationDataInvalid	0	Tipo di dati di sezione non valido.
k_ESteamPartyBeaconLocationDataName	1	Il nome, se presente, della sezione.
k_ESteamPartyBeaconLocationDataIconURLSmall		Se la sezione ha un'icona associata, questo è l'URL per l'immagine dell'icona in formato piccolo.
k_ESteamPartyBeaconLocationDataIconURLMedium		Se la sezione ha un'icona associata, questo è l'URL per l'immagine dell'icona in formato medio.
k_ESteamPartyBeaconLocationDataIconURLLarge		Se la sezione ha un'icona associata, questo è l'URL per l'immagine dell'icona in formato grande.

Typedef

Queste sono typedef definite per l'utilizzo con ISteamUserStats.

Nome	Tipo base	Descrizione
PartyBeaconID_t	uint64	Un handle a un segnale di un gruppo di Steam.