Merge pull request from SimoneStarace/master

Adding more code examples
This commit is contained in:
Tim Felgentreff 2021-06-29 22:14:14 +02:00 committed by GitHub
commit 7ff5b699de
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 233 additions and 7 deletions

View file

@ -362,11 +362,47 @@ static CAiType *GetAiTypesByName(const char *name)
}
/**
** <b>Description</b>
**
** Define an AI engine.
**
** @param l Lua state.
**
** @return FIXME: docu
**
** Example:
**
** <div class="example"><code>-- Those instructions will be executed forever
** local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the functions from start.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** -- The initial instructions the A.I has to execute
** local simple_ai = {
** function() return AiSleep(1800) end, -- Sleep for 1 in game minute
** function() return AiNeed("unit-town-hall") end, -- One Town Hall is needed
** function() return AiWait("unit-town-hall") end, -- Wait until the Town Hall is completed
** function() return AiSet("unit-peasant", 4) end, -- Make 4 peasants
** -- Basic buildings
** function() return AiSet("unit-farm", 4) end, -- Make 4 farms
** function() return AiWait("unit-farm") end, -- Wait until all 4 farms are build.
** function() return AiNeed("unit-human-barracks") end, -- Need a Barrarck
** function() return AiWait("unit-human-barracks") end, -- Wait until the Barracks has been built
** -- Defense force for the base
** function() return AiForce(1, {"unit-footman", 3}) end, -- Make a force of 3 footmen
** function() return AiWaitForce(1) end, -- Wait until the 3 footmen are trained
** function() return AiForceRole(1,"defend") end, -- Make this force as a defense force
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** -- function that calls the instructions in simple_ai inside DefineAi
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** -- Make an A.I for the human race that calls the function custom_ai
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclDefineAi(lua_State *l)
{
@ -504,11 +540,32 @@ static int CclAiGetRace(lua_State *l)
}
/**
** <b>Description</b>
**
** Get the number of cycles to sleep.
**
** @param l Lua state
**
** @return Number of return values
**
** Example:
**
** <div class="example"><code>local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the instructions forever.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** local simple_ai = {
** -- Get the number of cycles to sleep.
** function() return AiSleep(<b>AiGetSleepCycles()</b>) end,
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclAiGetSleepCycles(lua_State *l)
{
@ -582,11 +639,33 @@ static int CclAiDebugPlayer(lua_State *l)
}
/**
** <b>Description</b>
**
** Need a unit.
**
** @param l Lua state.
**
** @return Number of return values
**
** Example:
**
** <div class="example"><code>local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the instructions forever.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** local simple_ai = {
** function() return AiSleep(AiGetSleepCycles()) end,
** -- Tell to the A.I that it needs a Town Hall.
** function() return <b>AiNeed</b>("unit-town-hall") end,
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclAiNeed(lua_State *l)
{
@ -598,11 +677,37 @@ static int CclAiNeed(lua_State *l)
}
/**
** <b>Description</b>
**
** Set the number of units.
**
** @param l Lua state
**
** @return Number of return values
**
** Example:
**
** <div class="example"><code>local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the instructions forever.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** local simple_ai = {
** function() return AiSleep(AiGetSleepCycles()) end,
** -- Tell to the A.I that it needs a Town Hall.
** function() return AiNeed("unit-town-hall") end,
** -- Wait until the town-hall has been built.
** function() return AiWait("unit-town-hall") end,
** -- Tell to the A.I that it needs 4 peasants
** function() return <b>AiSet</b>("unit-peasant",4) end,
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclAiSet(lua_State *l)
{
@ -623,11 +728,35 @@ static int CclAiSet(lua_State *l)
}
/**
** <b>Description</b>
**
** Wait for a unit.
**
** @param l Lua State.
**
** @return Number of return values
**
** Example:
**
** <div class="example"><code>local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the instructions forever.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** local simple_ai = {
** function() return AiSleep(AiGetSleepCycles()) end,
** -- Tell to the A.I that it needs a Town Hall.
** function() return AiNeed("unit-town-hall") end,
** -- Wait until the Town Hall has been built.
** function() return <b>AiWait</b>("unit-town-hall") end,
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclAiWait(lua_State *l)
{
@ -703,9 +832,53 @@ static int CclAiPendingBuildCount(lua_State *l)
}
/**
** <b>Description</b>
**
** Define a force, a groups of units.
**
** @param l Lua state.
**
** Example:
**
** <div class="example"><code>local simple_ai_loop = {
** -- Sleep for 5 in game minutes
** function() return AiSleep(9000) end,
** -- Repeat the instructions forever.
** function() stratagus.gameData.AIState.loop_index[1 + AiPlayer()] = 0; return false; end,
** }
**
** local simple_ai = {
** function() return AiSleep(AiGetSleepCycles()) end,
** -- Tell to the A.I that it needs a Town Hall.
** function() return AiNeed("unit-town-hall") end,
** -- Wait until the Town Hall has been built.
** function() return AiWait("unit-town-hall") end,
** -- Tell to the A.I that it needs 4 peasants
** function() return AiSet("unit-peasant",4) end,
** -- Tell to the A.I that it needs a Barracks.
** function() return AiNeed("unit-human-barracks") end,
** -- Tell to the A.I that it needs a Lumbermill.
** function() return AiNeed("unit-elven-lumber-mill") end,
** -- Wait until the Barracks has been built.
** function() return AiWait("unit-human-barracks") end,
** -- Wait until the Lumbermill has been built.
** function() return AiWait("unit-elven-lumber-mill") end,
** -- Specify the force number 1 made only of 3 footmen
** function() return <b>AiForce</b>(1,{"unit-footman", 3}) end,
** -- Specify the force number 2 made only of 2 archers
** function() return <b>AiForce</b>(2,{"unit-archer", 2}) end,
** -- Specify the force number 3 made of 2 footmen and 1 archer
** function() return <b>AiForce</b>(3,{"unit-footman", 2, "unit-archer", 1}) end,
** -- Wait for all three forces
** function() return AiWaitForce(1) end,
** function() return AiWaitForce(2) end,
** function() return AiWaitForce(3) end,
** -- Execute the instructions in simple_ai_loop
** function() return AiLoop(simple_ai_loop, stratagus.gameData.AIState.loop_index) end,
** }
**
** function custom_ai() return AiLoop(simple_ai,stratagus.gameData.AIState.index) end
** DefineAi("example_ai","human","class_ai",custom_ai)</code></div>
*/
static int CclAiForce(lua_State *l)
{

View file

@ -1172,11 +1172,20 @@ static int CclSetFullGameName(lua_State *l)
}
/**
** <b>Description</b>
**
** Set God mode.
**
** @param l Lua state.
**
** @return The old mode.
**
** Example:
**
** <div class="example"><code>-- God Mode enabled
** SetGodMode(true)
** -- God Mode disabled
** SetGodMode(false)</code></div>
*/
static int CclSetGodMode(lua_State *l)
{
@ -1186,11 +1195,18 @@ static int CclSetGodMode(lua_State *l)
}
/**
** <b>Description</b>
**
** Get God mode.
**
** @param l Lua state.
**
** @return God mode.
**
** Example:
**
** <div class="example"><code>g_mode = GetGodMode()
** print(g_mode)</code></div>
*/
static int CclGetGodMode(lua_State *l)
{
@ -1479,7 +1495,14 @@ static int CclGetLocalPlayerName(lua_State *l)
}
/**
** <b>Description</b>
**
** Get Stratagus Version
**
** Example:
**
** <div class="example"><code>version = GetStratagusVersion()
** print(version)</code></div>
*/
static int CclGetStratagusVersion(lua_State *l)
{
@ -1489,7 +1512,14 @@ static int CclGetStratagusVersion(lua_State *l)
}
/**
** <b>Description</b>
**
** Get Stratagus Homepage
**
** Example:
**
** <div class="example"><code>url = GetStratagusHomepage()
** print(url)</code></div>
*/
static int CclGetStratagusHomepage(lua_State *l)
{

View file

@ -154,7 +154,15 @@ static CompareFunction GetCompareFunction(const char *op)
}
/**
** <b>Description</b>
**
** Return the number of units of a given unit-type and player at a location.
**
** Example:
**
** <div class="example"><code>-- Get the number of knights from player 1 from position 0,0 to 20,15
** num_units = GetNumUnitsAt(1,"unit-knight",{0,0},{20,15})
** print(num_units)</code></div>
*/
static int CclGetNumUnitsAt(lua_State *l)
{
@ -197,7 +205,18 @@ static int CclGetNumUnitsAt(lua_State *l)
}
/**
** <b>Description</b>
**
** Player has the quantity of unit-type near to unit-type.
**
** Example:
**
** <div class="example"><code>AddTrigger(
** function() return IfNearUnit(0,">",1,"unit-peasant","unit-town-hall") end,
** function()
** AddMessage("Player 0 has more than 1 peasant near the Town Hall")
** return false end
** )</code></div>
*/
static int CclIfNearUnit(lua_State *l)
{
@ -327,6 +346,8 @@ static int CclIfRescuedNearUnit(lua_State *l)
}
/**
** <b>Description</b>
**
** Returns the number of opponents of a given player.
*/
int GetNumOpponents(int player)

View file

@ -196,15 +196,11 @@ static int CclMapSound(lua_State *l)
**
** Ask the sound system to play the specified sound.
**
** @param l Lua state.
**
** Example:
**
** <div class="example">
** <code>
** PlaySound("rescue (orc)")
** </code>
** </div>
**
** @param l Lua state.
** <div class="example"><code>PlaySound("rescue (orc)")</code></div>
*/
static int CclPlaySound(lua_State *l)
{
@ -320,9 +316,15 @@ static int CclDefineGameSounds(lua_State *l)
}
/**
** <b>Description</b>
**
** Set the cut off distance.
**
** @param l Lua state.
**
** Example:
**
** <div class="example"><code>SetGlobalSoundRange(200)</code></div>
*/
static int CclSetGlobalSoundRange(lua_State *l)
{