Add native and forward documentation to include file

Rename some natives for better self explanatory.

forwards.cpp

@@ -43,7 +43,7 @@ SH_DECL_HOOK0_void(IDemoRecorder, StopRecording, SH_NOATTRIB, 0)
 
 void CForwardManager::Init()
 {
-	m_StartRecordingFwd = forwards->CreateForward("SourceTV_OnStartRecording", ET_Ignore, 3, NULL, Param_Cell, Param_String, Param_Cell);
+	m_StartRecordingFwd = forwards->CreateForward("SourceTV_OnStartRecording", ET_Ignore, 3, NULL, Param_Cell, Param_String);
 	m_StopRecordingFwd = forwards->CreateForward("SourceTV_OnStopRecording", ET_Ignore, 3, NULL, Param_Cell, Param_String, Param_Cell);
 }
 
@@ -72,7 +72,6 @@ void CForwardManager::OnStartRecording_Post(const char *filename, bool bContinuo
 
 	m_StartRecordingFwd->PushCell(0); // TODO: Get current hltvserver index
 	m_StartRecordingFwd->PushString(filename);
-	m_StartRecordingFwd->PushCell(bContinuously);
 	m_StartRecordingFwd->Execute();
 
 	RETURN_META(MRES_IGNORED);

natives.cpp

@@ -36,8 +36,8 @@
 
 extern const sp_nativeinfo_t sourcetv_natives[];
 
-// native SourceTV_GetHLTVServerCount();
+// native SourceTV_GetServerInstanceCount();
-static cell_t Native_GetHLTVServerCount(IPluginContext *pContext, const cell_t *params)
+static cell_t Native_GetServerInstanceCount(IPluginContext *pContext, const cell_t *params)
 {
 #if SOURCE_ENGINE == SE_CSGO
 	return hltvdirector->GetHLTVServerCount();
@@ -46,8 +46,8 @@ static cell_t Native_GetHLTVServerCount(IPluginContext *pContext, const cell_t *
 #endif
 }
 
-// native SourceTV_SelectHLTVServer();
+// native SourceTV_SelectServerInstance();
-static cell_t Native_SelectHLTVServer(IPluginContext *pContext, const cell_t *params)
+static cell_t Native_SelectServerInstance(IPluginContext *pContext, const cell_t *params)
 {
 #if SOURCE_ENGINE == SE_CSGO
 	if (params[1] < 0 || params[1] >= hltvdirector->GetHLTVServerCount())
@@ -69,8 +69,8 @@ static cell_t Native_SelectHLTVServer(IPluginContext *pContext, const cell_t *pa
 	return 0;
 }
 
-// native SourceTV_GetSelectedHLTVServer();
+// native SourceTV_GetSelectedServerInstance();
-static cell_t Native_GetSelectedHLTVServer(IPluginContext *pContext, const cell_t *params)
+static cell_t Native_GetSelectedServerInstance(IPluginContext *pContext, const cell_t *params)
 {
 	if (hltvserver == nullptr)
 		return -1;
@@ -120,6 +120,26 @@ static cell_t Native_GetLocalStats(IPluginContext *pContext, const cell_t *param
 	return 1;
 }
 
+// native bool:SourceTV_GetGlobalStats(&proxies, &slots, &specs);
+static cell_t Native_GetGlobalStats(IPluginContext *pContext, const cell_t *params)
+{
+	if (hltvserver == nullptr)
+		return 0;
+
+	int proxies, slots, specs;
+	hltvserver->GetGlobalStats(proxies, slots, specs);
+
+	cell_t *plProxies, *plSlots, *plSpecs;
+	pContext->LocalToPhysAddr(params[1], &plProxies);
+	pContext->LocalToPhysAddr(params[2], &plSlots);
+	pContext->LocalToPhysAddr(params[3], &plSpecs);
+
+	*plProxies = proxies;
+	*plSlots = slots;
+	*plSpecs = specs;
+	return 1;
+}
+
 // native SourceTV_GetBroadcastTick();
 static cell_t Native_GetBroadcastTick(IPluginContext *pContext, const cell_t *params)
 {
@@ -138,8 +158,8 @@ static cell_t Native_GetDelay(IPluginContext *pContext, const cell_t *params)
 	return sp_ftoc(hltvdirector->GetDelay());
 }
 
-// native bool:SourceTV_BroadcastHintMessage(const String:format[], any:...);
+// native bool:SourceTV_BroadcastScreenMessage(const String:format[], any:...);
-static cell_t Native_BroadcastHintMessage(IPluginContext *pContext, const cell_t *params)
+static cell_t Native_BroadcastScreenMessage(IPluginContext *pContext, const cell_t *params)
 {
 	if (hltvserver == nullptr)
 		return 0;
@@ -579,14 +599,15 @@ static cell_t Native_KickClient(IPluginContext *pContext, const cell_t *params)
 
 const sp_nativeinfo_t sourcetv_natives[] =
 {
-	{ "SourceTV_GetHLTVServerCount", Native_GetHLTVServerCount },
+	{ "SourceTV_GetServerInstanceCount", Native_GetServerInstanceCount },
-	{ "SourceTV_SelectHLTVServer", Native_SelectHLTVServer },
+	{ "SourceTV_SelectServerInstance", Native_SelectServerInstance },
-	{ "SourceTV_GetSelectedHLTVServer", Native_GetSelectedHLTVServer },
+	{ "SourceTV_GetSelectedServerInstance", Native_GetSelectedServerInstance },
 	{ "SourceTV_GetBotIndex", Native_GetBotIndex },
 	{ "SourceTV_GetLocalStats", Native_GetLocalStats },
+	{ "SourceTV_GetGlobalStats", Native_GetGlobalStats },
 	{ "SourceTV_GetBroadcastTick", Native_GetBroadcastTick },
 	{ "SourceTV_GetDelay", Native_GetDelay },
-	{ "SourceTV_BroadcastHintMessage", Native_BroadcastHintMessage },
+	{ "SourceTV_BroadcastScreenMessage", Native_BroadcastScreenMessage },
 	{ "SourceTV_BroadcastConsoleMessage", Native_BroadcastConsoleMessage },
 	{ "SourceTV_GetViewEntity", Native_GetViewEntity },
 	{ "SourceTV_GetViewOrigin", Native_GetViewOrigin },

sourcetv_test.sp

@@ -30,19 +30,19 @@ public OnPluginStart()
 	RegConsoleCmd("sm_speckick", Cmd_KickClient);
 }
 
-public SourceTV_OnStartRecording(hltvinstance, const String:filename[], bool:bContinuously)
+public SourceTV_OnStartRecording(instance, const String:filename[])
 {
-	PrintToServer("Started recording sourcetv #%d demo to %s (continuosly %d)", hltvinstance, filename, bContinuously);
+	PrintToServer("Started recording sourcetv #%d demo to %s", instance, filename);
 }
 
-public SourceTV_OnStopRecording(hltvinstance, const String:filename[], recordingtick)
+public SourceTV_OnStopRecording(instance, const String:filename[], recordingtick)
 {
-	PrintToServer("Stopped recording sourcetv #%d demo to %s (%d ticks)", hltvinstance, filename, recordingtick);
+	PrintToServer("Stopped recording sourcetv #%d demo to %s (%d ticks)", instance, filename, recordingtick);
 }
 
 public Action:Cmd_GetServerCount(client, args)
 {
-	ReplyToCommand(client, "SourceTV server count: %d", SourceTV_GetHLTVServerCount());
+	ReplyToCommand(client, "SourceTV server count: %d", SourceTV_GetServerInstanceCount());
 	return Plugin_Handled;
 }
 
@@ -58,14 +58,14 @@ public Action:Cmd_SelectServer(client, args)
 	GetCmdArg(1, sArg, sizeof(sArg));
 	new iInstance = StringToInt(sArg);
 	
-	SourceTV_SelectHLTVServer(iInstance);
+	SourceTV_SelectServerInstance(iInstance);
 	ReplyToCommand(client, "SourceTV selecting server: %d", iInstance);
 	return Plugin_Handled;
 }
 
 public Action:Cmd_GetSelectedServer(client, args)
 {
-	ReplyToCommand(client, "SourceTV selected server: %d", SourceTV_GetSelectedHLTVServer());
+	ReplyToCommand(client, "SourceTV selected server: %d", SourceTV_GetSelectedServerInstance());
 	return Plugin_Handled;
 }
 
@@ -126,7 +126,7 @@ public Action:Cmd_SendHintMessage(client, args)
 	GetCmdArgString(sMsg, sizeof(sMsg));
 	StripQuotes(sMsg);
 	
-	new bool:bSent = SourceTV_BroadcastHintMessage("%s", sMsg);
+	new bool:bSent = SourceTV_BroadcastScreenMessage("%s", sMsg);
 	ReplyToCommand(client, "SourceTV sending hint message (success %d): %s", bSent, sMsg);
 	return Plugin_Handled;
 }
@@ -166,7 +166,7 @@ public Action:Cmd_ForceChaseCameraShot(client, args)
 {
 	if (args < 1)
 	{
-		ReplyToCommand(client, "Usage: sm_startrecording <target> <ineye>");
+		ReplyToCommand(client, "Usage: sm_forcechasecam <target> <ineye>");
 		return Plugin_Handled;
 	}
 	

sourcetvmanager.inc

@@ -8,38 +8,295 @@
 #define MAX_SHOT_LENGTH				8.0  // maximum time of a cut (seconds)
 #define DEF_SHOT_LENGTH				6.0  // average time of a cut (seconds)
 
-native SourceTV_GetHLTVServerCount();
+/**
-native SourceTV_SelectHLTVServer(instance);
+ * Get the current amount of running SourceTV instances.
-native SourceTV_GetSelectedHLTVServer();
+ * Can usually only be 1 at max except for CSGO, which can have 2.
+ *
+ * @return SourceTV instance number count. 
+ */
+native SourceTV_GetServerInstanceCount();
+
+/**
+ * Select a SourceTV instance to operate the rest of the natives on.
+ * The first SourceTV to connect will always be selected by default.
+ * Most games only have 1 instance, so this might only be useful in CS:GO,
+ * which can have 2 instances running.
+ *
+ * @param instance The SourceTV instance number.
+ * @noreturn
+ * @error Invalid SourceTV instance number.
+ */
+native SourceTV_SelectServerInstance(instance);
+
+/**
+ * Get the index of the currently selected SourceTV server instance.
+ *
+ * @return Index of the selected SourceTV instance number or -1 if no SourceTV enabled.
+ */
+native SourceTV_GetSelectedServerInstance();
+
+/**
+ * Get the client index of the SourceTV bot.
+ *
+ * @return Client index of SourceTV bot.
+ */
 native SourceTV_GetBotIndex();
+
+/**
+ * Get stats of the local SourceTV instance.
+ * Returns only the stats of this server, don't include relays.
+ *
+ * You have to subtract the proxy count from the spectator count to 
+ * get the real spectator count, because the proxies take one spectator slot
+ * on the SourceTV server.
+ *
+ * @param proxies	Number of SourceTV proxies connected to this server.
+ * @param slots	Number of maximal available SourceTV spectator slots.
+ * @param specs Number of currently connected SourceTV spectators.
+ * @noreturn
+ */
 native bool:SourceTV_GetLocalStats(&proxies, &slots, &specs);
+
+/**
+ * Get stats of this SourceTV network.
+ * Only the current Master Proxy can give accurate numbers.
+ * Relay proxies only get updates from the master from time to time.
+ *
+ * You have to subtract the proxy count from the spectator count to 
+ * get the real spectator count, because the proxies take one spectator slot
+ * on the SourceTV server.
+ *
+ * @param proxies	Number of SourceTV proxies connected to all servers.
+ * @param slots	Number of maximal available SourceTV spectator slots on all servers.
+ * @param specs Number of currently connected SourceTV spectators on all servers.
+ * @noreturn
+ */
+native bool:SourceTV_GetGlobalStats(&proxies, &slots, &specs);
+
+/**
+ * Current broadcasted tick. Can be lower than the actual server tick,
+ * due to delay.
+ *
+ * @return Current broadcast tick from director.
+ */
 native SourceTV_GetBroadcastTick();
+
+/**
+ * Returns current delay in seconds. (tv_delay)
+ *
+ * @return Current delay in seconds.
+ */
 native Float:SourceTV_GetDelay();
-native bool:SourceTV_BroadcastHintMessage(const String:format[], any:...);
+
+/**
+ * Print a center message to all SourceTV spectators for ~2 seconds.
+ * Like the tv_msg command.
+ *
+ * @param format	The format string.
+ * @param ...	Variable number of format string arguments.
+ * @return	True if message was sent, false otherwise.
+ */
+native bool:SourceTV_BroadcastScreenMessage(const String:format[], any:...);
+
+/**
+ * Prints text to the console of all connected SourceTV spectators.
+ *
+ * @param format	The format string.
+ * @param ...	Variable number of format string arguments.
+ * @return	True if message was sent, false otherwise.
+ */
 native bool:SourceTV_BroadcastConsoleMessage(const String:format[], any:...);
-// get current view entity (PVS), 0 if coords are used
+
+
+
+
+/********************************************************************************
+ * SourceTV Director control
+ ********************************************************************************/
+
+/**
+ * Get entity index of current view entity (PVS) of the
+ * auto director. Check the view origin, if this returns 0.
+ * @see SourceTV_GetViewOrigin
+ *
+ * @return Current view entity index, 0 if coords are used.
+ */
 native SourceTV_GetViewEntity();
-// get current PVS origin
+
+/**
+ * Get origin of current view point if view entity is 0.
+ *
+ * @param view	Vector to store view position in.
+ * @noreturn
+ */
 native SourceTV_GetViewOrigin(Float:view[3]);
+
+/**
+ * Force the auto director to show a certain camera angle.
+ *
+ * @param pos	The camera position.
+ * @param angle	The camera angles (roll is unused).
+ * @param iTarget	Target entity to keep the camera pointed towards or 0 to use the angle.
+ * @param fow	Field of view of the camera.
+ * @param fDuration	Length of the shot in seconds.
+ * @return True if shot was created, false otherwise.
+ * @error Invalid target entity.
+ */
 native bool:SourceTV_ForceFixedCameraShot(Float:pos[], Float:angle[], iTarget, Float:fov, Float:fDuration = DEF_SHOT_LENGTH);
+
+/**
+ * Force the auto director to show a player.
+ *
+ * @param iTarget1	The target player to follow.
+ * @param iTarget2	The other player to keep the camera centered on or 0 to follow target1's view.
+ * @param distance	Distance of camera behind the player.
+ * @param phi	Up/down offset of view point.
+ * @param theta	Left/right offset of view point.
+ * @param bInEye	Show as in-eye camera of the target. Ignores all the other third-person settings.
+ * @param fDuration	Length of the shot in seconds.
+ * @return True if shot was created, false otherwise.
+ * @error Invalid target1 or target2 entity
+ */
 native bool:SourceTV_ForceChaseCameraShot(iTarget1, iTarget2, distance, phi, theta, bool:bInEye, Float:fDuration = DEF_SHOT_LENGTH);
 
+
+
+
+/********************************************************************************
+ * SourceTV demo recording
+ ********************************************************************************/
+
+/**
+ * Starts recording a SourceTV demo into the specified file.
+ * Only the master proxy can record demos.
+ *
+ * @param sFilename	Filename of the demo file.
+ * @return True if recording started, false otherwise.
+ */
 native bool:SourceTV_StartRecording(const String:sFilename[]);
+
+/**
+ * Stops recording a SourceTV demo.
+ *
+ * @return	True if recording stopped, false otherwise.
+ */
 native bool:SourceTV_StopRecording();
+
+/**
+ * Returns whether the SourceTV server is currently recording a demo.
+ *
+ * @return True if currently recording a SourceTV demo, false otherwise.
+ */
 native bool:SourceTV_IsRecording();
+
+/**
+ * Get the filename of the currently recorded demo.
+ *
+ * @param sFilename	Buffer to store the filename in.
+ * @param maxlen	Maximal length of the buffer.
+ * @return True if filename was written, false otherwise.
+ */
 native bool:SourceTV_GetDemoFileName(String:sFilename[], maxlen);
+
+/**
+ * Get current tick in the demofile.
+ *
+ * @return Current recording tick in the demofle.
+ */
 native SourceTV_GetRecordingTick();
+
+/**
+ * Print text to the demo console.
+ * This will show up when playing the demo back in the client console later.
+ *
+ * @param format	The format string.
+ * @param ...	Variable number of format string arguments.
+ *
+ * @return True if message was printed, false otherwise.
+ */
 native bool:SourceTV_PrintToDemoConsole(const String:format[], any:...);
 
+/**
+ * Called when a SourceTV demo starts being recorded.
+ * @see SourceTV_SelectServerInstance
+ *
+ * @param instance	The SourceTV instance of server recording.
+ * @param filename	The filename of the demo.
+ * @noreturn
+ */
+forward SourceTV_OnStartRecording(instance, const String:filename[]);
+
+/**
+ * Called when a SourceTV demo stops being recorded.
+ * @see SourceTV_SelectServerInstance
+ *
+ * @param instance	The SourceTV instance of server recording.
+ * @param filename	The filename of the demo.
+ * @param recordingtick	The tick length of the demo.
+ * @noreturn
+ */
+forward SourceTV_OnStopRecording(instance, const String:filename[], recordingtick);
+
+
+
+
+/********************************************************************************
+ * SourceTV spectator client handling
+ ********************************************************************************/
+
+/**
+ * Get currently connected SourcetV spectator count.
+ *
+ * @return	SourceTV spectator count.
+ */
 native SourceTV_GetSpectatorCount();
+
+/**
+ * Get the current client limit.
+ *
+ * @return	Maximal possible spectator count.
+ */
 native SourceTV_GetMaxClients();
+
+/**
+ * Get number of client slots (used & unused)
+ * Client slots are only allocated when they're needed.
+ * Use this when iterating spectators.
+ *
+ * @return	Number of client slots (used & unused)
+ */
 native SourceTV_GetClientCount();
+
+/**
+ * Returns if the spectator is connected.
+ *
+ * @param client	The spectator client index.
+ * @return	True if client is connected, false otherwise.
+ * @error	Invalid client index.
+ */
 native bool:SourceTV_IsClientConnected(client);
+
+/**
+ * Get the name of a SourceTV spectator client.
+ *
+ * @param client	The spectator client index.
+ * @param name	Buffer for the client name.
+ * @param maxlen	Maximal length of the buffer.
+ * @noreturn
+ * @error	Invalid client index or not connected.
+ */
 native SourceTV_GetSpectatorName(client, String:name[], maxlen);
+
+/**
+ * Kick a SourceTV spectator client.
+ * 
+ * @param client	The spectator client index.
+ * @param sReason	The kick reason.
+ * @noreturn
+ * @error	Invalid client index or not connected.
+ */
 native SourceTV_KickClient(client, const String:sReason[]);
 
-forward SourceTV_OnStartRecording(hltvinstance, const String:filename[], bool:bContinuously);
-forward SourceTV_OnStopRecording(hltvinstance, const String:filename[], recordingtick);
 
 /**
  * Do not edit below this line!
@@ -63,14 +320,15 @@ public Extension:__ext_stvmngr =
 #if !defined REQUIRE_EXTENSIONS
 public __ext_stvmngr_SetNTVOptional()
 {
-	MarkNativeAsOptional("SourceTV_GetHLTVServerCount");
+	MarkNativeAsOptional("SourceTV_GetServerInstanceCount");
-	MarkNativeAsOptional("SourceTV_SelectHLTVServer");
+	MarkNativeAsOptional("SourceTV_SelectServerInstance");
-	MarkNativeAsOptional("SourceTV_GetSelectedHLTVServer");
+	MarkNativeAsOptional("SourceTV_GetSelectedServerInstance");
 	MarkNativeAsOptional("SourceTV_GetBotIndex");
 	MarkNativeAsOptional("SourceTV_GetLocalStats");
+	MarkNativeAsOptional("SourceTV_GetGlobalStats");
 	MarkNativeAsOptional("SourceTV_GetBroadcastTick");
 	MarkNativeAsOptional("SourceTV_GetDelay");
-	MarkNativeAsOptional("SourceTV_BroadcastHintMessage");
+	MarkNativeAsOptional("SourceTV_BroadcastScreenMessage");
 	MarkNativeAsOptional("SourceTV_BroadcastConsoleMessage");
 	MarkNativeAsOptional("SourceTV_GetViewEntity");
 	MarkNativeAsOptional("SourceTV_GetViewOrigin");