From 3eb85ae4003fb95d5588dac66354ac07e47db732 Mon Sep 17 00:00:00 2001 From: Marco Cawthorne Date: Wed, 21 Dec 2022 17:09:35 -0800 Subject: [PATCH] Documentation improvements to various headers, also g_developer prints. --- src/gs-entbase/server/env_global.qc | 8 +- src/gs-entbase/server/func_button.qc | 2 +- src/gs-entbase/server/func_platrot.qc | 2 +- src/gs-entbase/server/func_tracktrain.qc | 2 + src/gs-entbase/server/func_train.qc | 2 + src/gs-entbase/server/path_corner.qc | 2 + src/shared/NSTrigger.h | 16 ++-- src/shared/NSTrigger.qc | 8 +- src/shared/colors.h | 4 + src/shared/effects.h | 24 ++--- src/shared/entities.h | 107 ++++++++++------------- 11 files changed, 88 insertions(+), 89 deletions(-) diff --git a/src/gs-entbase/server/env_global.qc b/src/gs-entbase/server/env_global.qc index 9647a98a..545fe941 100644 --- a/src/gs-entbase/server/env_global.qc +++ b/src/gs-entbase/server/env_global.qc @@ -45,14 +45,14 @@ public: /* overrides */ virtual void Save(float); - virtual void Restore(string,string); - virtual void SpawnKey(string,string); + virtual void Restore(string, string); + virtual void SpawnKey(string, string); virtual void Spawned(void); virtual void Trigger(entity, triggermode_t); virtual int GlobalPresent(string); - virtual void AddNewGlobal(string,globalstate_t); - virtual void SetGlobal(string,globalstate_t); + virtual void AddNewGlobal(string, globalstate_t); + virtual void SetGlobal(string, globalstate_t); }; diff --git a/src/gs-entbase/server/func_button.qc b/src/gs-entbase/server/func_button.qc index ee6b9bac..db02683b 100644 --- a/src/gs-entbase/server/func_button.qc +++ b/src/gs-entbase/server/func_button.qc @@ -62,7 +62,7 @@ original position. - "sounds" : Obsolete legacy key for HL/Q1 style buttons to decide which sounds to play. - "health" : Amount of damage this button takes before it triggers. Will reset. --------- OUTPUTS -------- +# OUTPUTS - "OnDamaged" : Fired when the button is damaged. - "OnPressed" : Fired when the button is pressed. - "OnUseLocked" : Fired when the button is used while locked. diff --git a/src/gs-entbase/server/func_platrot.qc b/src/gs-entbase/server/func_platrot.qc index 1c9c1d26..add89caa 100644 --- a/src/gs-entbase/server/func_platrot.qc +++ b/src/gs-entbase/server/func_platrot.qc @@ -43,7 +43,7 @@ A vertically moving platform that rotates. # NOTES Spins. --------- HISTORY -------- +# TRIVIA This entity was introduced in Half-Life (1998). */ class diff --git a/src/gs-entbase/server/func_tracktrain.qc b/src/gs-entbase/server/func_tracktrain.qc index 660d1c64..706efbb5 100644 --- a/src/gs-entbase/server/func_tracktrain.qc +++ b/src/gs-entbase/server/func_tracktrain.qc @@ -307,6 +307,8 @@ func_tracktrain::PathDone(void) return; } + NSLog("func_tracktrain (%s): Touched base with path_corner %S", targetname, target); + /* fire the path_corners' target */ if (eNode.m_strMessage) { eNode.Trigger(this, TRIG_TOGGLE); diff --git a/src/gs-entbase/server/func_train.qc b/src/gs-entbase/server/func_train.qc index b0b0748e..a8ec49da 100644 --- a/src/gs-entbase/server/func_train.qc +++ b/src/gs-entbase/server/func_train.qc @@ -255,6 +255,8 @@ func_train::PathDone(void) return; } + NSLog("func_train (%s): Touched base with path_corner %S", targetname, target); + /* fire the path_corners' target */ if (eNode.m_strMessage) { eNode.Trigger(this, TRIG_TOGGLE); diff --git a/src/gs-entbase/server/path_corner.qc b/src/gs-entbase/server/path_corner.qc index d145be3f..9e1e2b62 100644 --- a/src/gs-entbase/server/path_corner.qc +++ b/src/gs-entbase/server/path_corner.qc @@ -144,6 +144,7 @@ path_corner::Trigger(entity act, triggermode_t state) entity a; if (HasSpawnFlags(PC_FIREONCE) && m_iFired) { + NSLog("path_corner (%s) can only fire its targets once", targetname); return; } @@ -151,5 +152,6 @@ path_corner::Trigger(entity act, triggermode_t state) NSEntity trigger = (NSEntity)a; trigger.Trigger(act, state); m_iFired = TRUE; + NSLog("path_corner (%s) fired its %S targets", targetname, m_strMessage); } } diff --git a/src/shared/NSTrigger.h b/src/shared/NSTrigger.h index 3be58de8..8b258830 100644 --- a/src/shared/NSTrigger.h +++ b/src/shared/NSTrigger.h @@ -24,23 +24,25 @@ #define CENVGLOBAL_CVAR "env_global_data" +/** States for env_global data. */ typedef enum { + /** env_global data in question is set to 'off'. */ GLOBAL_OFF, + /** env_global data in question is set to 'on'. */ GLOBAL_ON, + /** env_global data in question is dead. */ GLOBAL_DEAD } globalstate_t; -typedef enum -{ - USE_TOGGLE, - USE_CONTINOUS -} usetype_t; - +/** The type of trigger activation. Used by trigger_auto and trigger_relay to specifically trigger states. TRIG_TOGGLE is the safe option, as it'll cause something to happen either way. The way an entity responds to the described state is up to how it is programmed. Many entities do not react to a change in state at all. */ typedef enum { + /** Trigger the target 'off', for doors that may tell them to close. */ TRIG_OFF, + /** Trigger the target 'on', for doors that may tell them to open. */ TRIG_ON, + /** Trigger the target the opposite to whatever they're currently in. */ TRIG_TOGGLE } triggermode_t; @@ -66,7 +68,7 @@ public: /** Called when we stopped touching the last touched entity. */ virtual void EndTouch(entity); - /* override */ + /* overrides */ virtual void SpawnKey(string,string); #ifdef SERVER diff --git a/src/shared/NSTrigger.qc b/src/shared/NSTrigger.qc index 12568a67..e8c8118b 100644 --- a/src/shared/NSTrigger.qc +++ b/src/shared/NSTrigger.qc @@ -38,7 +38,7 @@ NSTrigger::NSTrigger(void) void NSTrigger::Trigger(entity act, triggermode_t state) { - NSLog("^2%s::^3Input^7: Triggerd by %s with no consequence", + NSLog("^2%s::^3Trigger^7: Triggered by %s with no consequence", classname, act.classname); } @@ -130,16 +130,16 @@ NSTrigger::GetMaster(void) /* we couldn't find it, so let's not even bother going further */ if (!t) { NSLog("^2%s::^3GetMaster^7: Invalid master (%s), return success", - classname, m_strMaster); + classname, m_strMaster); return (1); } if (t.GetValue() == 1) NSLog("^2%s::^3GetMaster^7: %s learns %s ^2POSITIVE", - classname, targetname, m_strMaster); + classname, targetname, m_strMaster); else NSLog("^2%s::^3GetMaster^7: %s learns %s ^1NEGATIVE", - classname, targetname, m_strMaster); + classname, targetname, m_strMaster); return t.GetValue(); } diff --git a/src/shared/colors.h b/src/shared/colors.h index 683f9a78..e9aeea73 100644 --- a/src/shared/colors.h +++ b/src/shared/colors.h @@ -14,6 +14,8 @@ * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ +/** Takes a normalized color vector and returns the hexadecimal equivalent + for "funstrings". E.g. '1.0 0.0 0.0' becomes "^xF00". */ string Colors_RGB8_to_HEX(vector color) { @@ -50,6 +52,8 @@ Colors_RGB8_to_HEX(vector color) return out; } +/* Takes a 0-255 based color vector and returns the hexadecimal equivalent + for "funstrings". E.g. '255 0 0' becomes "^xF00". */ string Colors_RGB255_to_HEX(vector color) { diff --git a/src/shared/effects.h b/src/shared/effects.h index e22408c0..3593a044 100644 --- a/src/shared/effects.h +++ b/src/shared/effects.h @@ -23,19 +23,19 @@ #define EF_ADDITIVE (1<<5) /**< Render the entity additively. Also known as EF_FLAG2 in QW */ #define EF_BLUE (1<<6) /**< Cast a blue dynamic light. */ #define EF_RED (1<<7) /**< Cast a red dynamic light. */ -#define EF_UNUSED1 (1<<8) +#define EF_UNUSED1 (1<<8) /**< Unused. */ #define EF_FULLBRIGHT (1<<9) /**< Render entity without lighting. */ -#define EF_UNUSED2 (1<<10) -#define EF_UNUSED3 (1<<11) +#define EF_UNUSED2 (1<<10) /**< Unused. */ +#define EF_UNUSED3 (1<<11) /**< Unused. */ #define EF_NOSHADOW (1<<12) /**< Entity won't cast a shadow. */ #define EF_NODEPTHTEST (1<<13) /**< Entity renders through walls. */ -#define EF_UNUSED4 (1<<14) -#define EF_UNUSED5 (1<<15) -#define EF_UNUSED6 (1<<16) -#define EF_UNUSED7 (1<<17) +#define EF_UNUSED4 (1<<14) /**< Unused. */ +#define EF_UNUSED5 (1<<15) /**< Unused. */ +#define EF_UNUSED6 (1<<16) /**< Unused. */ +#define EF_UNUSED7 (1<<17) /**< Unused. */ #define EF_GREEN (1<<18) /**< Cast a green dynamic light. */ -#define EF_UNUSED8 (1<<19) -#define EF_UNUSED9 (1<<20) -#define EF_UNUSED10 (1<<21) -#define EF_UNUSED11 (1<<22) -#define EF_UNUSED12 (1<<23) \ No newline at end of file +#define EF_UNUSED8 (1<<19) /**< Unused. */ +#define EF_UNUSED9 (1<<20) /**< Unused. */ +#define EF_UNUSED10 (1<<21) /**< Unused. */ +#define EF_UNUSED11 (1<<22) /**< Unused. */ +#define EF_UNUSED12 (1<<23) /**< Unused. */ \ No newline at end of file diff --git a/src/shared/entities.h b/src/shared/entities.h index f1381e53..6bc5805c 100644 --- a/src/shared/entities.h +++ b/src/shared/entities.h @@ -14,50 +14,44 @@ * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* entity update identifiers */ -enum +/** Entity update identifiers */ +typedef enum { - ENT_NONE, - ENT_ENTITY, - ENT_ENTITYRENDERABLE, - ENT_SURFPROP, - ENT_BEAM, - ENT_PHYSICS, - ENT_MONSTER, - ENT_TALKMONSTER, - ENT_PLAYER, - ENT_SPECTATOR, - ENT_AMBIENTSOUND, - ENT_DLIGHT, - ENT_PROJECTEDTEXTURE, - ENT_FOGCONTROLLER, - ENT_LASER, - ENT_PARTSYSTEM, - ENT_SPRITE, - ENT_SPRAY, - ENT_DECAL, - ENT_OLDCAMERA, - ENT_MONITOR, - ENT_VEHICLE, - ENT_VEH_BRUSH, - ENT_VEH_TANKMORTAR, - ENT_VEH_4WHEEL, - ENT_PROPROPE, - ENT_BUBBLES, - ENT_SEPARATOR, -}; + ENT_NONE = 0, /**< invalid, but reserved. */ + ENT_ENTITY, /**< of type NSEntity */ + ENT_ENTITYRENDERABLE, /**< of type NSRenderableEntity */ + ENT_SURFPROP, /**< of type NSSurfacePropEntity */ + ENT_PHYSICS, /**< of type NSPhysicsEntity */ + ENT_MONSTER, /**< of type NSMonster */ + ENT_TALKMONSTER, /**< of type NSTalkMonster */ + ENT_PLAYER, /**< of type NSClientPlayer */ + ENT_SPECTATOR, /**< of type NSClientSpectator */ + ENT_AMBIENTSOUND, /**< of type ambient_generic */ + ENT_BEAM, /**< of type env_beam */ + ENT_DLIGHT, /**< of type light_dynamic */ + ENT_PROJECTEDTEXTURE, /**< of type env_projectedtexture */ + ENT_FOGCONTROLLER, /**< of type env_fog_controller */ + ENT_LASER, /**< of type env_laser */ + ENT_PARTSYSTEM, /**< of type info_particle_system */ + ENT_SPRITE, /**< of type env_sprite */ + ENT_SPRAY, /**< of type spray */ + ENT_DECAL, /**< of type infodecal */ + ENT_OLDCAMERA, /**< of type trigger_camera */ + ENT_MONITOR, /**< of type func_monitor */ + ENT_VEHICLE, /**< Reserved. */ + ENT_VEH_BRUSH, /**< of type func_vehicle */ + ENT_VEH_TANKMORTAR, /**< of type func_tankmortar */ + ENT_VEH_4WHEEL, /**< of type prop_vehicle_driveable */ + ENT_PROPROPE, /**< of type prop_rope */ + ENT_BUBBLES, /**< of type env_bubbles */ + ENT_SEPARATOR, /**< This is a separator. This separator is used by you to add game-specific networked entities. When declaring your own entity-update types, you want the first value to equal ENT_SEPARATOR at all times to ensure you'll not be overriding existing slots. */ +} entupdate_t; -/* -================= -Entity_FindClosest - -Returns the closest point entity of a given classname. -world means it failed. most likely. -================= -*/ +/** Returns the closest point entity of a given classname. +Returns 'world' or '__NULL__' if it fails to find anything. */ entity -Entity_FindClosest(entity target, string cname) +Entity_FindClosest(entity startTarget, string className) { entity best = world; float bestdist; @@ -65,8 +59,8 @@ Entity_FindClosest(entity target, string cname) bestdist = 9999999; - for (entity e = world; (e = find(e, classname, cname));) { - dist = vlen(target.origin - e.origin); + for (entity e = world; (e = find(e, classname, className));) { + dist = vlen(startTarget.origin - e.origin); if (dist < bestdist) { bestdist = dist; @@ -78,40 +72,33 @@ Entity_FindClosest(entity target, string cname) } -/* -================= -Entity_SelectRandom - -Returns a random entity of a given classname. -Check for world at all times. If world is returned then the given classname -will most likely never return anything valid. -================= -*/ +/** Returns a random entity of a given classname. +If world or '__NULL__' is returned, then the given classname is not present in the map. */ entity -Entity_SelectRandom(string cname) +Entity_SelectRandom(string className) { entity spot = world; - float max = 0; + int max = 0i; - /* count our max count */ - for (entity e = world; (e = find(e,::classname, cname));) { + /* count the total number of entities of the desired class */ + for (entity e = world; (e = find(e, ::classname, className));) { max++; } - /* immediately exit out */ - if (max == 0) { - print(sprintf("^1Error: %s is not present on this map.\n", cname)); + /* immediately exit out if we've got none */ + if (max < 1i) { + print(sprintf("^1Error: %s is not present on this map.\n", className)); return __NULL__; } /* select a random point */ for (int i = random(1, max); i > 0; i--) { - spot = find(spot, classname, cname); + spot = find(spot, ::classname, className); } /* we might end up not finding anything, wrap around? */ if (spot == __NULL__) { - spot = find(spot, classname, cname); + spot = find(spot, ::classname, className); } /* we should have returned something valid now */