Lua documentation and function update

code/game/lua_entity.c

@@ -8,16 +8,17 @@ extern qboolean G_CallSpawn(gentity_t *ent);
 #ifdef G_LUA
 
 /***
-Module to access entity functions and manage enities. Documentation under work.
+Module to access entity functions and manage enities.
 @module entiy
 */
 
-// entity.MMBRefit()
+/***
-// this is just a function called from lua
+This is just a function called from lua it should be called before any other model work
-// it should be called before any other model work
+this will loop trough all misc_model_breakables and checks their model-string against those listed here
-// this will loop trough all misc_model_breakables and checks their model-string against those listed here
+if it finds a match it will apply the associated splashDamage, splashRadius and s.powerups (material of chunks) to the entity
-// if it finds a match it will apply the associated splashDamage, splashRadius and s.powerups (material of chunks) to the entity
+this is the only failsafe way i can think of to do these kind of refit
-// this is the only failsafe way i can think of to do these kind of refit
+@function MMBRefit
+*/
 static int Entity_MMBRefit(lua_State * L)
 {
 	gentity_t		*MMB;
@@ -36,10 +37,11 @@ static int Entity_MMBRefit(lua_State * L)
 		|| !Q_stricmp( arg2, "stasis1" ) || !Q_stricmp( arg2, "stasis2" ) || !Q_stricmp( arg2, "stasis3" )
 		|| !Q_stricmp( arg2, "tour/deck01" ) || !Q_stricmp( arg2, "tour/deck02" ) || !Q_stricmp( arg2, "tour/deck03" ) || !Q_stricmp( arg2, "tour/deck04" ) || !Q_stricmp( arg2, "tour/deck05" ) || !Q_stricmp( arg2, "tour/deck08" ) || !Q_stricmp( arg2, "tour/deck09" ) || !Q_stricmp( arg2, "tour/deck10" ) || !Q_stricmp( arg2, "tour/deck11" ) || !Q_stricmp( arg2, "tour/deck15" )
 		|| !Q_stricmp( arg2, "tutorial" )
-		|| !Q_stricmp( arg2, "voy1" ) || !Q_stricmp( arg2, "voy13" ) || !Q_stricmp( arg2, "voy14" ) || !Q_stricmp( arg2, "voy15" ) || !Q_stricmp( arg2, "voy16" ) || !Q_stricmp( arg2, "voy17" ) || !Q_stricmp( arg2, "voy2" ) || !Q_stricmp( arg2, "voy20" ) || !Q_stricmp( arg2, "voy3" ) || !Q_stricmp( arg2, "voy4" ) || !Q_stricmp( arg2, "voy5" ) || !Q_stricmp( arg2, "voy6" ) || !Q_stricmp( arg2, "voy7" ) || !Q_stricmp( arg2, "voy8" ) || !Q_stricmp( arg2, "voy9" ) )
+		|| !Q_stricmp( arg2, "voy1" ) || !Q_stricmp( arg2, "voy13" ) || !Q_stricmp( arg2, "voy14" ) || !Q_stricmp( arg2, "voy15" ) || !Q_stricmp( arg2, "voy16" ) || !Q_stricmp( arg2, "voy17" ) || !Q_stricmp( arg2, "voy2" ) || !Q_stricmp( arg2, "voy20" ) || !Q_stricmp( arg2, "voy3" ) || !Q_stricmp( arg2, "voy4" ) || !Q_stricmp( arg2, "voy5" ) || !Q_stricmp( arg2, "voy6" ) || !Q_stricmp( arg2, "voy7" ) || !Q_stricmp( arg2, "voy8" ) || !Q_stricmp( arg2, "voy9" ) ) {
-		MMB = NULL; //init MMB here to do sth pointless
+			MMB = NULL; //init MMB here to do sth pointless
-	else
+	} else {
-		return 1; //we are not on one of the supported maps
+		return 0; //we are not on one of the supported maps
+	}
 
 	while((MMB = G_Find(MMB, FOFS(classname), "misc_model_breakable" )) != NULL  ){//loop while you find these
 		//borg maps
@@ -76,12 +78,15 @@ static int Entity_MMBRefit(lua_State * L)
 		}else continue;//we are not looking for this kind of MMB
 	}
 
-	return 1;
+	return 0;
 }
 
 
-// entity.GetTarget(entity ent)
+/***
-// returns a target entity of ent
+Returns a target entity of ent.
+@function GetTarget
+@return Target of the entity.
+*/
 static int Entity_GetTarget(lua_State * L)
 {
 	lent_t*		lent = NULL;
@@ -107,15 +112,17 @@ static int Entity_GetTarget(lua_State * L)
 	}
 
 	Lua_PushEntity(L, t);
-
 	LUA_DEBUG("END - entity.GetTarget");
 	return 1;
 }
 
-// entity.FindBModel(integer bmodelnum)
+/***
-// Returns the entity with the brush model bmodelnumber. 
+Returns the entity with the brush model bmodelnumber. 
-// This is the only failsafe way to find brush entities as the 
+This is the only failsafe way to find brush entities as the 
-// entity number is different when you load a map local or join a server.
+entity number is different when you load a map local or join a server.
+@function FindBModel
+@param number Number of the brush model.
+*/
 static int Entity_FindBModel(lua_State *L) {
 	gentity_t*	ent = NULL;
 	int			bmodel;
@@ -138,8 +145,12 @@ static int Entity_FindBModel(lua_State *L) {
 	return 1;
 }
 
-// entity.FindNumber(integer entnum)
+/***
-// Returns the entity with the entity number entnum.
+Returns the entity with the entity number entnum.
+@function FindNumber
+@param number Entity number.
+@return Entity for the given entity number.
+*/
 static int Entity_FindNumber(lua_State * L)
 {
 	int			entnum;
@@ -161,8 +172,12 @@ static int Entity_FindNumber(lua_State * L)
 	return 1;
 }
 
-// entity.Find(string targetname)
+/***
-// Returns the first entity found that has a targetname of targetname.
+Returns the first entity found that has a targetname of targetname.
+@function Find
+@param targetname
+@return First entity found that has the given targetname.
+*/
 static int Entity_Find(lua_State * L)
 {
 	gentity_t* t = NULL;
@@ -182,10 +197,14 @@ static int Entity_Find(lua_State * L)
 	return 1;
 }
 
-// entity.FindMMB(vector origin)
+/***
-// Returns the misc_model_breakable entity that has a matching MMB->s.origin.
+Returns the misc_model_breakable entity that has a matching MMB->s.origin.
-// Requires vector as input.
+Requires vector as input.
-// You can get the s.origin ingame as an admin/developer by pointing at the MMB ingame and using the /getorigin-command.
+You can get the s.origin ingame as an admin/developer by pointing at the MMB ingame and using the /getorigin-command.
+@function FindMMB
+@param vector Origin of misc_model_breakable.
+@return Matching entity.
+*/
 static int Entity_FindMMB(lua_State * L)
 {
 	gentity_t		*t = NULL, *MMB = NULL;
@@ -193,6 +212,11 @@ static int Entity_FindMMB(lua_State * L)
 	
 	vec = Lua_GetVector(L, 2);
 
+	if(vec == NULL) {
+		lua_pushnil(L);
+		return 1;
+	}
+
 	while((MMB = G_Find(MMB, FOFS(classname), "misc_model_breakable")) != NULL){
 		origin = MMB->s.origin;
 		if(vec[0] == origin[0] && vec[1] == origin[1] && vec[2] == origin[2]){
@@ -211,9 +235,12 @@ static int Entity_FindMMB(lua_State * L)
 	return 1;
 }
 
-// entity.Use(entity ent)
+/***
-// Uses ent.
+Uses the given entity.
-// returns succes or fail
+@function Use
+@param ent Entity to use.
+@return Success or failure.
+*/
 static int Entity_Use(lua_State * L)
 {
 	lent_t* lent = NULL;

code/game/lua_mover.c

@@ -12,6 +12,7 @@ A module for entity movement, especially for mover entities such as doors.
 Stops translational movement on ent immediately.
 @function Halt
 @param ent Entity or entity number.
+@return Success or failure.
 */
 static int Mover_Halt(lua_State *L) {
 	lent_t		*lent;
@@ -20,12 +21,21 @@ static int Mover_Halt(lua_State *L) {
 	
 	if(lua_isnumber(L, 1)) {
 		id =  luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -39,13 +49,15 @@ static int Mover_Halt(lua_State *L) {
 	ent->nextTrain = NULL;
 	trap_LinkEntity(ent);
 	LUA_DEBUG("Mover_Halt - return: halted ent");
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 /***
 Stops rotational movement on ent immediately.
 @function HaltAngles
 @param ent Entity or entity number.
+@return Success or failure.
 */
 static int Mover_HaltAngles(lua_State * L)
 {
@@ -55,12 +67,21 @@ static int Mover_HaltAngles(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -73,7 +94,9 @@ static int Mover_HaltAngles(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_HaltAngles - return: halted ent");
 	}
-	return 0;
+
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 extern void Reached_Train(gentity_t *ent);
@@ -86,6 +109,7 @@ Moves an entity like a func_train entity. Targets have to be path_corner entitie
 @param mover Entity to move.
 @param target path_corner entity to move to.
 @param speed Speed to move with to the first path_corner.
+@return Success or failure.
  */
 static int Mover_AsTrain(lua_State * L)
 {
@@ -100,31 +124,50 @@ static int Mover_AsTrain(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 	if(luaL_checkint(L, 2)) {
 		tid = luaL_checkint(L, 2);
-		if(tid < 0 || tid > MAX_GENTITIES - 1) return 1;
+		if(tid < 0 || tid > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		targ = &g_entities[tid];
-		if(!targ) return 1;
+		if(targ == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		tlent = Lua_GetEntity(L, 2);
-		if(!tlent || tlent->e == NULL) return 1;
+		if(!tlent || tlent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		targ = tlent->e;
 	}
 
 	LUA_DEBUG("Mover_AsTrain - start: ent=%d target=%d speed=%f", ent->s.number, targ->s.number, speed);
 
-	if(!ent || !targ)
+	if(ent == NULL || targ == NULL)
 	{
 		LUA_DEBUG("Mover_AsTrain - return: ent or/and target missing");
-		return 0;
+		lua_pushboolean(L, qfalse);
+		return 1;
 	}
 	if(speed < 1)
 	{
@@ -157,7 +200,8 @@ static int Mover_AsTrain(lua_State * L)
 	{
 		G_SetOrigin(ent, ent->pos2);
 		LUA_DEBUG("Mover_AsTrain - return: snapped to target, length too small length=%f", length);
-		return 0;
+		lua_pushboolean(L, qtrue);
+		return 1;
 	}
 
 	ent->s.pos.trDuration = length * 1000 / speed;
@@ -167,7 +211,8 @@ static int Mover_AsTrain(lua_State * L)
 	SetMoverState(ent, MOVER_1TO2, level.time);
 
 	LUA_DEBUG("Mover_AsTrain - return: moving to target, length=%f duration=%d", length, ent->s.pos.trDuration);
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 /***
@@ -177,12 +222,14 @@ Sets the angles of ent to the specified values. Values are sorted Pitch (around
 @param y Pitch.
 @param z Yaw.
 @param x Roll.
+@return Success or failure.
 */
 /***
 Sets the angles of ent to the specified value.
 @function SetAngles
 @param ent Entity or entity number.
 @param agles Vector containing the new angles.
+@return Success or failure.
 */
 static int Mover_SetAngles(lua_State * L)
 {
@@ -194,12 +241,21 @@ static int Mover_SetAngles(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -222,7 +278,8 @@ static int Mover_SetAngles(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_SetAngles - return: moved");
 	}
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 /***
@@ -232,11 +289,13 @@ Sets the angles of ent to the specified values. Values are sorted Pitch (around
 @param y Pitch.
 @param z Yaw.
 @param x Roll.
+@return Success or failure.
 */
 /***
 Sets the angles of ent to the specified value.
 @function SetAngles2
 @param vec Vector containing the new angles.
+@return Success or failure.
 */
 static int Mover_SetAngles2(lua_State * L)
 {
@@ -248,12 +307,21 @@ static int Mover_SetAngles2(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -275,7 +343,8 @@ static int Mover_SetAngles2(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_SetAngles2 - return: moved");
 	}
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 /***
@@ -285,12 +354,14 @@ Set the position of ent to the specified value.
 @param x X coordinates.
 @param y Y coordinates.
 @param z Z coordinates.
+@return Success or failure.
 */
 /***
 Set the position of ent to the specified value.
 @function SetPosition
 @param ent Entity or entity number.
 @param vec Vector containing the new position.
+@return Success or failure.
 */
 static int Mover_SetPosition(lua_State * L)
 {
@@ -302,12 +373,22 @@ static int Mover_SetPosition(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL)
+		{
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -329,7 +410,8 @@ static int Mover_SetPosition(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_SetPosition - return: moved");
 	}
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 static void SetTrajectoryLinear(trajectory_t * tr, const float speed, const vec3_t endPosition)
@@ -354,6 +436,7 @@ Rotates ent with a given speed (in degrees per second) to the specified values.
 @param y Pitch.
 @param z Yaw.
 @param x Roll.
+@return Succes or failure.
 */
 /***
 Rotates ent with a given speed (in degrees per second) to the specified values. 
@@ -361,6 +444,7 @@ Rotates ent with a given speed (in degrees per second) to the specified values.
 @param ent Entity or entity number.
 @param speed Speed to rotate with.
 @param vec Vector conataining target angles.
+@return Success or failure.
 */
 static int Mover_ToAngles(lua_State * L)
 {
@@ -373,12 +457,21 @@ static int Mover_ToAngles(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 || id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 || id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L, 1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -405,7 +498,8 @@ static int Mover_ToAngles(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_ToAngles - return: moving");
 	}
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 /***
@@ -416,6 +510,7 @@ Moves ent with a given speed to the specified values. Can also be stowed in a ve
 @param x X coordinates.
 @param y Y coordinates.
 @param z Z coordinates.
+@return Success or failure.
 */
 static int Mover_ToPosition(lua_State * L)
 {
@@ -428,12 +523,21 @@ static int Mover_ToPosition(lua_State * L)
 
 	if(lua_isnumber(L, 1)) {
 		id = luaL_checkint(L, 1);
-		if(id < 0 ||id > MAX_GENTITIES - 1) return 1;
+		if(id < 0 ||id > MAX_GENTITIES - 1) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = &g_entities[id];
-		if(!ent) return 1;
+		if(ent == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 	} else {
 		lent = Lua_GetEntity(L,1);
-		if(!lent || !lent->e) return 1;
+		if(lent == NULL || lent->e == NULL) {
+			lua_pushboolean(L, qfalse);
+			return 1;
+		}
 		ent = lent->e;
 	}
 
@@ -461,7 +565,8 @@ static int Mover_ToPosition(lua_State * L)
 		trap_LinkEntity(ent);
 		LUA_DEBUG("Mover_ToPosition - return: moving");
 	}
-	return 0;
+	lua_pushboolean(L, qtrue);
+	return 1;
 }
 
 static const luaL_Reg lib_mover[] = {