Unvanquished - User contributions [en-gb]

Bot skillset modding

2023-05-31T12:07:50Z

Afontain: Update the referenced PR

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2635.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills</code> which set the initial skills for the various skill levels.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills</code> cvar to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> to 0 and write the <code>g_skillset_baseSkills</code> list.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the <code>g_skillset_baseSkills</code> cvar to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in <code>g_skillset_baseSkills</code> for your desired skill threshold. This will exclude a skill from the random selection but still allow the budget to select the other skills. This works because the base skill list takes precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-31T12:07:16Z

Afontain: Clarify language

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills</code> which set the initial skills for the various skill levels.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills</code> cvar to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> to 0 and write the <code>g_skillset_baseSkills</code> list.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the <code>g_skillset_baseSkills</code> cvar to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in <code>g_skillset_baseSkills</code> for your desired skill threshold. This will exclude a skill from the random selection but still allow the budget to select the other skills. This works because the base skill list takes precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-27T22:32:25Z

Afontain: Rename and merge g_skillset_baseSkills_levelN cvars to only one: g_skillset_baseSkills

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills</code> which set the initial skills for the various skill levels.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills</code> cvar to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> to 0 and write the <code>g_skillset_baseSkills</code> list.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the <code>g_skillset_baseSkills</code> cvar to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in the base skill list for your desired skill levels. This works because putting skills in that list will prevent them from being chosen randomly, but the base skill lists take precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-16T22:58:07Z

Afontain: Rename g_skillset_baseSkills.levelN cvar to g_skillset_baseSkills_levelN

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills_levelN</code> which set the initial skills for the N-th skill level.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills_levelN</code> cvars to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> to 0 and write the various <code>g_skillset_baseSkills_levelN</code> lists.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the <code>g_skillset_baseSkills_levelN</code> cvars to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in the base skill list for your desired skill levels. This works because putting skills in that list will prevent them from being chosen randomly, but the base skill lists take precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot design

2023-05-16T22:17:59Z

Afontain: /* Computer vision */

= Generalities =

The main situations we want bots to work in are:

* In a game where a single user plays in a team against a team of bots (let's call this ''1v0'')
* In a game where a few users play against each others, with a considerable amount of bots on both teams (let's call this ''1v1, 2v2'', etc.)
* In a game where a considerable number of players team up to play against a horde of bots (let's call this ''PvE'')
* In a game where a single user (or few users) play against a considerably bigger number of other users (let's call this ''1v3'', etc.)

In games where bots are a minority in both teams, bots are not that important. When playing PvE, the variations of bot skill are also not very important, as players can't feel like they got an unfairly weak ally.

Bots are built from roughly 3 different "modules":

* navigation, which is done with a combination of A* or Dijkstra and navmeshes;
* decision, which is done with the paradigm of behavior trees;
* computer vision, to complete what navmeshes can not provide;

== Navigation ==

All bots should be able to reach any part of the map that does not require special training.

== Decision ==

=== Bot levels ===

For historical reasons, bots have a range of skills numbered from 1 to 9, all integers.

Skill 1 is considered to be training dummies, while skill 9 is considered as the *user* is the training dummy.

Skill 5 should never be so strong that an average player can not kill it in duel, nor so weak than an average player considers the bot negligible.

==== Bot personalities ====

In 2022 and early 2023, we did some experiments about giving each bot a personality. The idea was to have a number of skills that are valuable in playing. Each bot would receive its unique set of skills, by some random selection. That would make them different from each other.

Some examples of "bot skills" we used are: various alien trick moves, the ability to aim better than other bots, smartly buying human equipment/weapons and using the human medkit.

The pros of this approach:

* Bots do not behave all the same. That makes them more difficult to predict.
* Bots simulate real users more accurately.

The cons:

* It is harder to balance bots against each other. We would have to test a significant subset of all possible combinations. This matters a lot in 1v1 or 2v2. It matters even more in 1v3.
* Users will discover what skills are more valuable. They can tweak the skills the bots on their team have, by voting to remove them and add them again until they hit a sweet spot.

Those two cons should be mitigated by having sufficiently many skills and skills that have well adapted costs: that is by having costs reflect the skill's usefulness.

== Computer vision ==

Bots should be able to detect any enemy in their FoV. It would be nice to have bots not being too good at finding hiden buildables on the roof. This makes hiding eggs unfun and next to impossible in the current state. Unless they are placed outside of a navmesh, in which case bots are totally unable to discover them.

To improve this and make bots feel more like human players, we should make bots:
* not automatically know the egg locations when rushing: https://github.com/Unvanquished/Unvanquished/pull/2683
* attack enemies that are visible but outside the navmesh
* for human bots, not be as great at spotting things vertically as they are with thing horizontally (like regular humans)
* maybe not discovering things always with the same reliability — but this would bring randomness.

== Non-cheating ==

Bots should not perform any action that could not be performed by a non-bot client. This is believed to be true in the current state. This property does take some care to maintain, as bot functions often act directly on sgame state rather than using client commands.

It would be nice if additionally, bots only used ''information'' that could have been learned by a normal player. This is far from true in the current state: for example, bots have omniscience of all buildables in the level.

When playing against bots, it should not ''feel'' like a bot is cheating, i.e. doing something that a human player could not have done. The bot should not have impossibly fast reaction times or seem like it's using an aimbot, triggerbot, etc.

== Current Questions ==

* Should we keep bot personalities, or make all bots the same?
* How much randomness should be involved in a bot's behavior?
* How many details of bot configuration should be hard-coded, and how many should be exposed by cvars?

Bot design

2023-05-16T22:07:19Z

Afontain: /* Bot levels */

= Generalities =

The main situations we want bots to work in are:

* In a game where a single user plays in a team against a team of bots (let's call this ''1v0'')
* In a game where a few users play against each others, with a considerable amount of bots on both teams (let's call this ''1v1, 2v2'', etc.)
* In a game where a considerable number of players team up to play against a horde of bots (let's call this ''PvE'')
* In a game where a single user (or few users) play against a considerably bigger number of other users (let's call this ''1v3'', etc.)

In games where bots are a minority in both teams, bots are not that important. When playing PvE, the variations of bot skill are also not very important, as players can't feel like they got an unfairly weak ally.

Bots are built from roughly 3 different "modules":

* navigation, which is done with a combination of A* or Dijkstra and navmeshes;
* decision, which is done with the paradigm of behavior trees;
* computer vision, to complete what navmeshes can not provide;

== Navigation ==

All bots should be able to reach any part of the map that does not require special training.

== Decision ==

=== Bot levels ===

For historical reasons, bots have a range of skills numbered from 1 to 9, all integers.

Skill 1 is considered to be training dummies, while skill 9 is considered as the *user* is the training dummy.

Skill 5 should never be so strong that an average player can not kill it in duel, nor so weak than an average player considers the bot negligible.

==== Bot personalities ====

In 2022 and early 2023, we did some experiments about giving each bot a personality. The idea was to have a number of skills that are valuable in playing. Each bot would receive its unique set of skills, by some random selection. That would make them different from each other.

Some examples of "bot skills" we used are: various alien trick moves, the ability to aim better than other bots, smartly buying human equipment/weapons and using the human medkit.

The pros of this approach:

* Bots do not behave all the same. That makes them more difficult to predict.
* Bots simulate real users more accurately.

The cons:

* It is harder to balance bots against each other. We would have to test a significant subset of all possible combinations. This matters a lot in 1v1 or 2v2. It matters even more in 1v3.
* Users will discover what skills are more valuable. They can tweak the skills the bots on their team have, by voting to remove them and add them again until they hit a sweet spot.

Those two cons should be mitigated by having sufficiently many skills and skills that have well adapted costs: that is by having costs reflect the skill's usefulness.

== Computer vision ==

Bots should be able to detect any enemy in their FoV.

== Non-cheating ==

Bots should not perform any action that could not be performed by a non-bot client. This is believed to be true in the current state. This property does take some care to maintain, as bot functions often act directly on sgame state rather than using client commands.

It would be nice if additionally, bots only used ''information'' that could have been learned by a normal player. This is far from true in the current state: for example, bots have omniscience of all buildables in the level.

When playing against bots, it should not ''feel'' like a bot is cheating, i.e. doing something that a human player could not have done. The bot should not have impossibly fast reaction times or seem like it's using an aimbot, triggerbot, etc.

== Current Questions ==

* Should we keep bot personalities, or make all bots the same?
* How much randomness should be involved in a bot's behavior?
* How many details of bot configuration should be hard-coded, and how many should be exposed by cvars?

Bot skillset modding

2023-05-16T21:46:38Z

Afontain: add code tags around cvar names

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills.levelN</code> which set the initial skills for the N-th skill level.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills.levelN</code> cvars to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> to 0 and write the various <code>g_skillset_baseSkills.levelN</code> lists.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the <code>g_skillset_baseSkills.levelN</code> cvars to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in the base skill list for your desired skill levels. This works because putting skills in that list will prevent them from being chosen randomly, but the base skill lists take precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-16T21:45:13Z

Afontain: /* Skilltree in pure random "mode" */ add code tag

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills.levelN</code> which set the initial skills for the N-th skill level.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the <code>g_skillset_baseSkills.levelN</code> cvars to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set g_skillset_budgetHumans and g_skillset_budgetAliens to 0 and write the various g_skillset_baseSkills.levelN lists.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the g_skillset_baseSkills.levelN cvars to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in the base skill list for your desired skill levels. This works because putting skills in that list will prevent them from being chosen randomly, but the base skill lists take precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-16T19:44:56Z

Afontain: Finish documenting it as of the state in https://github.com/Unvanquished/Unvanquished/pull/2697, 16 of May

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png|thumbnail|An example of skilltree structure]]

Each skill is a boolean on/off tag, that has some chance of being unlocked. As long as there are skill points to spend, the next skill is selected randomly.

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget want.

[[File:Bot-skilltree-advanced.png|thumbnail|Here's an advanced example where the buy-modern-armor skill is a base-skill (always enabled) and the prefer-armor skill is disabled (never selected randomly)]]

The second command, <code>/devbotgraphskilltree [skillLevel]</code> saves a <code>.dot</code> graph file that can be converted to an image. For example one can do this in the game console:
/devbotgraphskilltree 5
game/bot-skilltree-alien.dot written
game/bot-skilltree-human.dot written

Then (e.g.) this in a terminal:
$ dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && xdg-open result.png

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

== Modifying and tweaking the skilltree ==

Depending on your objectives, which maybe to offer diverse and interesting bots e.g. for a juggernaut mod, or to provide very predictable bots e.g. for a tournament, you may have different desire for bot customisations. The current implementation of the skilltree should be flexible enough to allow this.

The skill selection process is customised by these cvars:
* <code>g_skillset_baseSkills.levelN</code> which set the initial skills for the N-th skill level.
* <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code>
* <code>g_skillset_disabledSkills</code>, which will prevent skills from being randomly selected.

=== Skilltree in pure random "mode" ===

You sometime want to have maximum randomness in your opponents, with a purely random skill setup. For example this can make PvE games or Juggernaut fights more interesting.

You can do that by:
* setting the g_skillset_baseSkills.levelN cvars to an empty string
* giving some skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

In the current implementation, you get <code>floor(budget*(2+skillLevel)/9)</code> skill points to spend so that the whole budget is unlocked at skill level 7 while keeping a reasonable amount of points at lower skills. The code for this is in <code>src/sgame/sg_bot_skilltree.cpp</code>, in <code>BotPickSkillset</code>'s definition of <code>skill_points</code>.

=== Skilltree in pure deterministic "mode" ===

You sometime want purely deterministic bots, for example for tournaments or for easier inital balancing. This is the way I'd like Unvanquished to go towards on the long term.

If you wish to have perfectly identical bots for some skill levels, you can set g_skillset_budgetHumans and g_skillset_budgetAliens to 0 and write the various g_skillset_baseSkills.levelN lists.

=== Skilltree in mixed "mode" ===

There is a third way, where one can define "vital" skills that have to be selected for given skill levels. You can do this by setting the base skills are always selected, and give more budget than those initial skills cost, so that the leftover skill points (if any) will be used randomly.

You can do that by
* setting the g_skillset_baseSkills.levelN cvars to the base required skills for each level, then
* giving some extra skill funds for your bots to randomly choose from, using the <code>g_skillset_budgetHumans</code> and <code>g_skillset_budgetAliens</code> cvars.

💡️ Tip: You can even have some skills mandatory at some skill levels and forbidden from the other skill levels. To do that, you add the skill in the <code>g_skillset_disabledSkills</code> list AND in the base skill list for your desired skill levels. This works because putting skills in that list will prevent them from being chosen randomly, but the base skill lists take precedence.

The visualisation features explained in [[#Visualising_the_skilltree]] will be very useful in this situation, make sure you know how to use them.

Bot skillset modding

2023-05-16T14:49:55Z

Afontain: Created page with "This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697. == Basic principle == File:Bot-skilltree-basic.png == Visualising th..."

This wiki page explains the skilltree as of https://github.com/Unvanquished/Unvanquished/pull/2697.

== Basic principle ==

[[File:Bot-skilltree-basic.png]]

== Visualising the skilltree ==

There are two commands, <code>/devbotcountskillpoints</code> and <code>/devbotgraphskilltree [skillLevel]</code> that can help handling the skilltree.

The first command, <code>/devbotcountskillpoints</code>, just prints a message with the total cost of (reachable) skills in the tree for each team. This can help figuring out the maximum budget you may want.

The second command saves a <code>.dot</code> graph file that can be converted to an image. For example one can do:
dot -Tpng ~/.local/share/unvanquished/game/bot-skilltree-human.dot > result.png && eog result.png.

[[File:Bot-skilltree-advanced.png]]

If one gives the skill level as an argument argument to the <code>/devbotgraphskilltree</code> command, it will print the statistics for that skill level, with colors for the disabled and forced skills.

File:Bot-skilltree-basic.png

2023-05-16T14:49:32Z

Afontain: /* Summary */

== Summary ==
Some simple skilltree example for human bots

The code versions is as of 2023-05-16, with https://github.com/Unvanquished/Unvanquished/pull/2697.

== Licencing ==
{{licenses/cc-by-4.0}}

File:Bot-skilltree-basic.png

2023-05-16T14:49:16Z

Afontain: Afontain uploaded a new version of File:Bot-skilltree-basic.png

== Summary ==
Some skilltree example for human bots with one base skill (force-enabled) and one disabled skill.

The code versions is as of 2023-05-16, with https://github.com/Unvanquished/Unvanquished/pull/2697.
== Licencing ==
{{licenses/cc-by-4.0}}

File:Bot-skilltree-advanced.png

2023-05-16T14:47:50Z

Afontain: Some skilltree example for human bots with one base skill (force-enabled) and one disabled skill. The code versions is as of 2023-05-16, with https://github.com/Unvanquished/Unvanquished/pull/2697.

File:Bot-skilltree-basic.png

2023-05-16T14:46:51Z

Afontain:

File:Bot-skilltree-basic.png

2023-05-16T14:45:33Z

Afontain: The state of the skilltree as it is with https://github.com/Unvanquished/Unvanquished/pull/2697, 2023-05-16.

== Summary ==
The state of the skilltree as it is with https://github.com/Unvanquished/Unvanquished/pull/2697, 2023-05-16.
== Licencing ==
{{licenses/cc-by-4.0}}

Bot design

2023-04-17T18:23:33Z

Afontain:

The main situations we want bots to work in are:

* In a game where a single user plays in a team against a team of bots (let's call this ''1v0'')
* In a game where a few users play against each others, with a considerable amount of bots on both teams (let's call this ''1v1, 2v2'', etc.)
* In a game where a considerable number of players team up to play against a horde of bots (let's call this ''PvE'')
* In a game where a single user (or few users) play against a considerably bigger number of other users (let's call this ''1v3'', etc.)

In games where bots are a minority in both teams, bots are not that important. When playing PvE, the variations of bot skill are also not very important, as players can't feel like they got an unfairly weak ally.

== Bot personalities ==

In 2022 and early 2023, we did some experiments about giving each bot a personality. The idea was to have a number of skills that are valuable in playing. Each bot would receive its unique set of skills, by some random selection. That would make them different from each other.

Some examples of "bot skills" we used are: various alien trick moves, the ability to aim better than other bots, smartly buying human equipment/weapons and using the human medkit.

The pros of this approach:

* Bots do not behave all the same. That makes them more difficult to predict.
* Bots simulate real users more accurately.

The cons:

* It is harder to balance bots against each other. We would have to test a significant subset of all possible combinations. This matters a lot in 1v1 or 2v2. It matters even more in 1v3.
* Users will discover what skills are more valuable. They can tweak the skills the bots on their team have, by voting to remove them and add them again until they hit a sweet spot.

Formats/DPK

2022-11-06T11:30:48Z

Afontain: correct sections

[[Category:Formats]]
[[Category:Mapping]]
== About the DPK name ==

''DPK'' stands for ''“Dæmon PacKage”'', the DPK VFS is a ''PacKage''-based VFS leveraging ''Dependency'' mechanism.

== DPK format specification ==

The DPK format extends the legacy PK3 format with dependency mechanism and versionning and was implemented for the need of the [https://unvanquished.net/ Unvanquished game]. Like the PK3 VFS, the DPK VFS allows to extend and override an existing file system using packages, see the [[Filesystem]] page to see how it works. The {{engine}} is the reference implementation, it has been introduced under this name in Unvanquished 0.51.0 release.

There is two DPK formats: archive and directory format.

* Archive format is for distribution (commonly named ''DPK''), this format is meant to be easily shareable over the network and auto-downloadable by game clients;
: The archive format uses the PKZIP container (the well-known ''zip'' format) with a ''.dpk'' extension.
* Directory format is for editing/testing (commonly named ''DPKDIR'');
: The directory format is a simple plain directory with a ''.dpkdir'' extension.

=== Package naming ===

Format: ''<package-name>_<version-string>.<extension>''

* package-name: name of the package, some names are prefixed
:* mandatory prefix for map packages: ''“map-”'' (the engine will not find neither load the map otherwise)
:* recommended prefix for texture packages: ''"tex-”''
:* recommended prefix for various resource packages (like a package providing both sounds effects, textures, models and animation for a given player model) : ''"res-”''
:* forbidden characters: underscore, dot ''[_.]''
* version: version of the package, follows [https://salsa.debian.org/dpkg-team/dpkg/-/blob/main/lib/dpkg/version.c dpkg's version comparison priority], see [[Packaging version guidelines]] for Unvanquished specificities.
:* characters allowed: alphanumeric plus hyphen and tilde ''[a-zA-Z0-9~-]''
* extension: ''“dpk”'' for archive, ''“dpkdir”'' for directory

Examples:

* ''unvanquished_0.51.0.dpk''
* ''map-parpax_0.5d-viech.dpk''
* ''tex-vega_src.dpkdir''
* ''res-players_src.dpkdir''

=== Package layout ===

Package archive or directory can contain a ''DEPS'' file on its root directory containing a list of other package it depends on.

Each package reproduces the file system tree from his root.

=== DEPS file format ===

* One package name per line, optional explicit version separated from package name using a whitespace;
* Dependencies are loaded giving priority to first ones if multiple package provides different files under the same name.

Example:

<pre>
tex-space
tex-pk02 1.0
tex-vega 0.4b
</pre>

Loading a package providing this ''DEPS'' file will trigger the game engine to also load the ''tex-space'' package (the most recent version found), and to load the 1.0 version of the ''tex-pk02'' package and the 0.4b version of the tex-vega package.

== Software compatibility ==

Software that support DPK format and have first class Unvanquished support:

* [[Engine|Dæmon]] game engine: full dpk/dpkdir support with dependency and version handling, support in master branch;
* [[Tools/NetRadiant|NetRadiant]] level editor: full dpk/dpkdir support with dependency and version handling, support in master branch;
* [[Tools/q3map2|q3map2]] map compiler (NetRadiant tree): basic dpk/dkdir support, loads all dpk/dpkdir it finds, support in master branch;
* [[Tools/Chameleon|Chameleon]] texture replacement editor: basic dpk/dpkdir support, loads all dpk/dpkdir it finds, support in master branch;
* [[Tools/Urcheon|Urcheon]] package build tool: basic dpkdir support, loads all dpkdir it finds, support in master branch;
* [[XQF]] game server browser: basic dpk support, loads all dpk it finds, support in master branch.

Other software that are known to support DPK format and have working Unvanquished support:

* [[Tools/GtkRadiant|GtkRadiant]] level editor: basic dpk/dkdir support in master branch, loads all dpk/dpkdir it finds, support in master branch, prefer using NetRadiant if possible and if NetRadiant is not possible prefer q3map2 from NetRadiant tree;
* [[Tools/q3map2|q3map2]] map compiler (GtkRadiant tree): basic dpk/dkdir support, loads all dpk/dpkdir it finds, support in master branch, not recommended for Dæmon mapping due to feature lacking.

Other software that are known to support DPK format but have not working Unvanquished support:

* [[tools/DarkRadiant|DarkRadiant]] level editor: basic dpk/dpkdir support, loads all dpk/dpkdir it finds, support in standard releases (just add "dpk" to game file), not yet usable for Dæmon/Unvanquished mapping due to some Q3 map parsing issues.

==Merging several DPK==
{{OutOfDate}}

To combine all packages together, at a Bash shell:

$ cd [[Game locations|<var>data directory</var>]]/pkg; mkdir tmp; for pk3 in pak{{0..9},A}.pk3; do unzip -o $pk3 -d tmp; done

(If there are additional <code>pak*</code> files (e.g., <code>pakB.pk3</code>), edit the pattern accordingly (e.g., to <code>pak{{0..9},{A..B}}.pk3</code>.)

This will place the cumulative contents (i.e., as the engine would see them) of all the <code>pak*.pk3</code> archives into a new <code>tmp/</code> directory in your data directory.

Testing

2022-11-06T11:29:48Z

Afontain: fix spacing

[[Category:Testing]]
==Reporting bugs==

Please see the [[Bug_reporting|bug reporting]] page. This page is about helping modders and developers testing their changes.

==Debugging==

To create a debug build, change <code>CMAKE_BUILD_TYPE</code> in CMake from <code>Release</code> to <code>Debug</code>, then [[Compiling_the_source|compile]].

You may find it necessary to set <code>in_nograb</code> to <code>1</code> to disable pointer grabbing so that you may use your debugger.

===Debugging with gdb===

Start gdb as follows:

$ gdb --args ./daemon +devmap chasm

If the program segfaults, a backtrace is very useful to the developers in determining the source of the problem. At the debugger prompt, type <code>bt</code>:

(gdb) bt

===Debugging with Xcode===

With Xcode 4, even if you did not build the game with Xcode, you may still use its facilities for debugging.

# Open any project. If necessary, create a new one. It may contain anything.
# Click "Product" on the menu bar and navigate to "Attach to Process". Look for "daemon" listed under "Applications".

After a moment, the application will be ready for debugging.

See the [https://developer.apple.com/library/mac/#documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW1 Xcode 4 User Guide] for more information.

==Live Testing==

===Starting a testing session===

Start the game, and enter the following command:

/devmap <var>map name</var>

===Adding bots===

Like fish in a fish bowl, they can bring some activity in a map.

/bot fill 5 # add 5 bots

You can also have a look at all the <code>g_bot_*</code> cvars, they are quite interesting. There is even a graphical user interface for these!

===Moving around with ease and spawning anywhere===

You can pass through walls and fly around using <code>/noclip</code>, and you can spawn anywhere you want using <code>/devteam h</code> for humans or <code>/teamteam a</code> for aliens. That's very practical and can allow you to start from an empty map.

To load an empty map without having the game finishing immediately, you can use <code>g_neverEnd</code>. This can help porting maps.

===The <code>/give</code> command===

The /give will give you an easy way to test situations without being blocked by funds or team advancement.

/team a # join aliens
/give momentum # give all the momentum you can to your team
/give bp 100 # get 100 build points free
/give funds # get rich quick! I swear it's not a pyramid scheme!
/give all # get all personal things you can get, in addition to money (BP and momentum are independant)

You can also combine several commands into one, for example you can test advanced dragoon really quickly

=== Some misc useful cvars===

* <code>cg_drawSpeed</code> to see how fast you are moving, <code>/set cg_drawSpeed 2</code> even brings an histogram.
* <code>cg_drawBBOX</code> to see how big or small the bounding box are
* <code>cg_drawDebugDistance</code> to give you an idea of how far away of you a distance of "100 quake units" is
* <code>timescale</code> setting this will make everything faster, or slower. Be careful that if you set it too low (say less than 0.1) the graphical console will take a lot of time to visibly appear, but you can still type in it. For example to do <code>/timescale 1</code> again.
* <code>g_freeFundPeriod</code> to change how often you and other clients are gifted money. This can be an alternative to making bots ignore limits that can give a bit more diversity in their choices and behaviours (rich bots will always rush, for example)

==Debugging Graphics==

* <code>cg_draw2D</code> can allow you to disable 2D drawing. It may be useful if you want to ignore 2D performances from your benchmarks

There probably exist proprietary tools for your platform. For example AMD used to have gDEBugger, and [https://gpuopen.com/archived/gpu-perfstudio/ GPU PerfStudio] proprietary debuggers.

===apitrace===

[https://apitrace.github.io/ apitrace] is an open-source tool that records every graphics API call made by an application. After the application has closed, you can step through individual calls to the graphics API, allowing you to
* see the result exactly as it would appear following each call,
* see graphs of API usage, and
* inspect buffers.

Linux users can install it from their package manager, for example:

sudo apt install apitrace-tracers apitrace-gui

Windows users can [http://people.freedesktop.org/~jrfonseca/apitrace/ download a build].

==General Tips==

===Miscellaneous===

* To stress test the engine's ability to display a large number of buildables, you can tweak <code>g_BPInitialBudget</code> and build as much as you wish.
* To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular [[Formats/DPK|.dpk archive]]) use the <code>/which</code> command with the relative path to the asset as an argument. You can use tab-completion.

For example, this means that you are effectively the new version of an UI file:

/which ui/shared/circlemenu.rcss
File "ui/shared/circlemenu.rcss" found in "/home/me/unv/Unvanquished/pkg/unvanquished_src.dpkdir/"

==Viewing Runtime Information==

The engine and game logic provide a number of commands for viewing information about its current state.

==Testing materials and textures==

See {{Subpage|Materials}}.

==Testing maps==

See {{Subpage|Maps}}.

==Testing models==

See {{Subpage|Models}}.

Testing

2022-11-06T11:27:30Z

Afontain: Continue cleaning

[[Category:Testing]]

==Reporting bugs==

Please see the [[Bug_reporting|bug reporting]] page. This page is about helping modders and developers testing their changes.

==Debugging==

To create a debug build, change <code>CMAKE_BUILD_TYPE</code> in CMake from <code>Release</code> to <code>Debug</code>, then [[Compiling_the_source|compile]].

You may find it necessary to set <code>in_nograb</code> to <code>1</code> to disable pointer grabbing so that you may use your debugger.

===Debugging with gdb===

Start gdb as follows:

$ gdb --args ./daemon +devmap chasm

If the program segfaults, a backtrace is very useful to the developers in determining the source of the problem. At the debugger prompt, type <code>bt</code>:

(gdb) bt

===Debugging with Xcode===

With Xcode 4, even if you did not build the game with Xcode, you may still use its facilities for debugging.

# Open any project. If necessary, create a new one. It may contain anything.
# Click "Product" on the menu bar and navigate to "Attach to Process". Look for "daemon" listed under "Applications".

After a moment, the application will be ready for debugging.

See the [https://developer.apple.com/library/mac/#documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW1 Xcode 4 User Guide] for more information.

==Live Testing==

===Starting a testing session===

Start the game, and enter the following command:

/devmap <var>map name</var>

===Adding bots===

Like fish in a fish bowl, they can bring some activity in a map.

/bot fill 5 # add 5 bots

You can also have a look at all the <code>g_bot_*</code> cvars, they are quite interesting. There is even a graphical user interface for these!

===Moving around with ease and spawning anywhere===

You can pass through walls and fly around using <code>/noclip</code>, and you can spawn anywhere you want using <code>/devteam h</code> for humans or <code>/teamteam a</code> for aliens. That's very practical and can allow you to start from an empty map.

To load an empty map without having the game finishing immediately, you can use <code>g_neverEnd</code>. This can help porting maps.

===The <code>/give</code> command===

The /give will give you an easy way to test situations without being blocked by funds or team advancement.

/team a # join aliens
/give momentum # give all the momentum you can to your team
/give bp 100 # get 100 build points free
/give funds # get rich quick! I swear it's not a pyramid scheme!
/give all # get all personal things you can get, in addition to money (BP and momentum are independant)

You can also combine several commands into one, for example you can test advanced dragoon really quickly

=== Some misc useful cvars===

* <code>cg_drawSpeed</code> to see how fast you are moving, <code>/set cg_drawSpeed 2</code> even brings an histogram.
* <code>cg_drawBBOX</code> to see how big or small the bounding box are
* <code>cg_drawDebugDistance</code> to give you an idea of how far away of you a distance of "100 quake units" is
* <code>timescale</code> setting this will make everything faster, or slower. Be careful that if you set it too low (say less than 0.1) the graphical console will take a lot of time to visibly appear, but you can still type in it. For example to do <code>/timescale 1</code> again.
* <code>g_freeFundPeriod</code> to change how often you and other clients are gifted money. This can be an alternative to making bots ignore limits that can give a bit more diversity in their choices and behaviours (rich bots will always rush, for example)

==Debugging Graphics==

* <code>cg_draw2D</code> can allow you to disable 2D drawing. It may be useful if you want to ignore 2D performances from your benchmarks

There probably exist proprietary tools for your platform. For example AMD used to have gDEBugger, and [https://gpuopen.com/archived/gpu-perfstudio/ GPU PerfStudio] proprietary debuggers.

===apitrace===

[https://apitrace.github.io/ apitrace] is an open-source tool that records every graphics API call made by an application. After the application has closed, you can step through individual calls to the graphics API, allowing you to
* see the result exactly as it would appear following each call,
* see graphs of API usage, and
* inspect buffers.

Linux users can install it from their package manager, for example:

sudo apt install apitrace-tracers apitrace-gui

Windows users can [http://people.freedesktop.org/~jrfonseca/apitrace/ download a build].

==General Tips==

===Miscellaneous===

* To stress test the engine's ability to display a large number of buildables, you can tweak <code>g_BPInitialBudget</code> and build as much as you wish.
* To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular [[Formats/DPK|.dpk archive]]) use the <code>/which</code> command with the relative path to the asset as an argument. You can use tab-completion.

For example, this means that you are effectively the new version of an UI file:

/which ui/shared/circlemenu.rcss
File "ui/shared/circlemenu.rcss" found in "/home/me/unv/Unvanquished/pkg/unvanquished_src.dpkdir/"

==Viewing Runtime Information==

The engine and game logic provide a number of commands for viewing information about its current state.

==Testing materials and textures==

See {{Subpage|Materials}}.

==Testing maps==

See {{Subpage|Maps}}.

==Testing models==

See {{Subpage|Models}}.

Formats/DPK

2022-11-06T11:24:09Z

Afontain: Move text that was on the Testing page (https://wiki.unvanquished.net/index.php?title=Testing)

[[Category:Formats]]
[[Category:Mapping]]
== About the DPK name ==

''DPK'' stands for ''“Dæmon PacKage”'', the DPK VFS is a ''PacKage''-based VFS leveraging ''Dependency'' mechanism.

== DPK format specification ==

The DPK format extends the legacy PK3 format with dependency mechanism and versionning and was implemented for the need of the [https://unvanquished.net/ Unvanquished game]. Like the PK3 VFS, the DPK VFS allows to extend and override an existing file system using packages, see the [[Filesystem]] page to see how it works. The {{engine}} is the reference implementation, it has been introduced under this name in Unvanquished 0.51.0 release.

There is two DPK formats: archive and directory format.

* Archive format is for distribution (commonly named ''DPK''), this format is meant to be easily shareable over the network and auto-downloadable by game clients;
: The archive format uses the PKZIP container (the well-known ''zip'' format) with a ''.dpk'' extension.
* Directory format is for editing/testing (commonly named ''DPKDIR'');
: The directory format is a simple plain directory with a ''.dpkdir'' extension.

=== Package naming ===

Format: ''<package-name>_<version-string>.<extension>''

* package-name: name of the package, some names are prefixed
:* mandatory prefix for map packages: ''“map-”'' (the engine will not find neither load the map otherwise)
:* recommended prefix for texture packages: ''"tex-”''
:* recommended prefix for various resource packages (like a package providing both sounds effects, textures, models and animation for a given player model) : ''"res-”''
:* forbidden characters: underscore, dot ''[_.]''
* version: version of the package, follows [https://salsa.debian.org/dpkg-team/dpkg/-/blob/main/lib/dpkg/version.c dpkg's version comparison priority], see [[Packaging version guidelines]] for Unvanquished specificities.
:* characters allowed: alphanumeric plus hyphen and tilde ''[a-zA-Z0-9~-]''
* extension: ''“dpk”'' for archive, ''“dpkdir”'' for directory

Examples:

* ''unvanquished_0.51.0.dpk''
* ''map-parpax_0.5d-viech.dpk''
* ''tex-vega_src.dpkdir''
* ''res-players_src.dpkdir''

=== Package layout ===

Package archive or directory can contain a ''DEPS'' file on its root directory containing a list of other package it depends on.

Each package reproduces the file system tree from his root.

=== DEPS file format ===

* One package name per line, optional explicit version separated from package name using a whitespace;
* Dependencies are loaded giving priority to first ones if multiple package provides different files under the same name.

Example:

<pre>
tex-space
tex-pk02 1.0
tex-vega 0.4b
</pre>

Loading a package providing this ''DEPS'' file will trigger the game engine to also load the ''tex-space'' package (the most recent version found), and to load the 1.0 version of the ''tex-pk02'' package and the 0.4b version of the tex-vega package.

== Software compatibility ==

Software that support DPK format and have first class Unvanquished support:

* [[Engine|Dæmon]] game engine: full dpk/dpkdir support with dependency and version handling, support in master branch;
* [[Tools/NetRadiant|NetRadiant]] level editor: full dpk/dpkdir support with dependency and version handling, support in master branch;
* [[Tools/q3map2|q3map2]] map compiler (NetRadiant tree): basic dpk/dkdir support, loads all dpk/dpkdir it finds, support in master branch;
* [[Tools/Chameleon|Chameleon]] texture replacement editor: basic dpk/dpkdir support, loads all dpk/dpkdir it finds, support in master branch;
* [[Tools/Urcheon|Urcheon]] package build tool: basic dpkdir support, loads all dpkdir it finds, support in master branch;
* [[XQF]] game server browser: basic dpk support, loads all dpk it finds, support in master branch.

Other software that are known to support DPK format and have working Unvanquished support:

* [[Tools/GtkRadiant|GtkRadiant]] level editor: basic dpk/dkdir support in master branch, loads all dpk/dpkdir it finds, support in master branch, prefer using NetRadiant if possible and if NetRadiant is not possible prefer q3map2 from NetRadiant tree;
* [[Tools/q3map2|q3map2]] map compiler (GtkRadiant tree): basic dpk/dkdir support, loads all dpk/dpkdir it finds, support in master branch, not recommended for Dæmon mapping due to feature lacking.

Other software that are known to support DPK format but have not working Unvanquished support:

* [[tools/DarkRadiant|DarkRadiant]] level editor: basic dpk/dpkdir support, loads all dpk/dpkdir it finds, support in standard releases (just add "dpk" to game file), not yet usable for Dæmon/Unvanquished mapping due to some Q3 map parsing issues.

===Merging several DPK===
{{OutOfDate}}

To combine all packages together, at a Bash shell:

$ cd [[Game locations|<var>data directory</var>]]/pkg; mkdir tmp; for pk3 in pak{{0..9},A}.pk3; do unzip -o $pk3 -d tmp; done

(If there are additional <code>pak*</code> files (e.g., <code>pakB.pk3</code>), edit the pattern accordingly (e.g., to <code>pak{{0..9},{A..B}}.pk3</code>.)

This will place the cumulative contents (i.e., as the engine would see them) of all the <code>pak*.pk3</code> archives into a new <code>tmp/</code> directory in your data directory.

Testing

2022-11-06T10:16:57Z

Afontain: Update quite a bit the page, and give testing tips

{{OutOfDate}}
[[Category:Testing]]
==Reporting a bug==

If you wish to report a bug, you may want to have a look at [[bug reporting]] instead

==Debugging==

To create a debug build, change <code>CMAKE_BUILD_TYPE</code> in CMake from <code>Release</code> to <code>Debug</code>, then [[Compiling_the_source|compile]].

You may find it necessary to set <code>in_nograb</code> to <code>1</code> to disable pointer grabbing so that you may use your debugger.

===Debugging with gdb===

Start gdb as follows:

$ gdb --args ./daemon +devmap chasm

If the program segfaults, a backtrace is very useful to the developers in determining the source of the problem. At the debugger prompt, type <code>bt</code>:

(gdb) bt

===Debugging with Xcode===

With Xcode 4, even if you did not build the game with Xcode, you may still use its facilities for debugging.

# Open any project. If necessary, create a new one. It may contain anything.
# Click "Product" on the menu bar and navigate to "Attach to Process". Look for "daemon.i386" listed under "Applications".

After a moment, the application will be ready for debugging.

See the [https://developer.apple.com/library/mac/#documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW1 Xcode 4 User Guide] for more information.

==Live Testing==

===Starting a testing session===

Start the game, and enter the following command:

/devmap <var>map name</var>

===Adding bots===

Like fish in a fish bowl, they can bring some activity in a map.

/bot fill 5 # add 5 bots

You can also have a look at all the <code>g_bot_*</code> cvars, they are quite interesting. There is even a graphical user interface for these!

===The <code>/give</code> command===

The /give will give you an easy way to test situations without being blocked by funds or team advancement.

/team a # join aliens
/give momentum # give all the momentum you can to your team
/give bp 100 # get 100 build points free
/give funds # get rich quick! I swear it's not a pyramid scheme!
/give all # get all personal things you can get, in addition to money (BP and momentum are independant)

You can also combine several commands into one, for example you can test advanced dragoon really quickly

=== Some misc useful cvars===

* <code>cg_drawSpeed</code> to see how fast you are moving, <code>/set cg_drawSpeed 2</code> even brings an histogram.
* <code>cg_drawBBOX</code> to see how big or small the bounding box are
* <code>cg_drawDebugDistance</code> to give you an idea of how far away of you a distance of "100 quake units" is
* <code>timescale</code> setting this will make everything faster, or slower. Be careful that if you set it too low (say less than 0.1) the graphical console will take a lot of time to visibly appear, but you can still type in it. For example to do <code>/timescale 1</code> again.
* <code>g_freeFundPeriod</code> to change how often you and other clients are gifted money. This can be an alternative to making bots ignore limits that can give a bit more diversity in their choices and behaviours (rich bots will always rush, for example)

==Debugging Graphics==

* <code>cg_draw2D</code> can allow you to disable 2D drawing. It may be useful if you want to ignore 2D performances from your benchmarks

There probably exist proprietary tools for your platform. For example AMD used to have gDEBugger, and [https://gpuopen.com/archived/gpu-perfstudio/ GPU PerfStudio] proprietary debuggers.

===apitrace===

[https://apitrace.github.io/ apitrace] is an open-source tool that records every graphics API call made by an application. After the application has closed, you can step through individual calls to the graphics API, allowing you to
* see the result exactly as it would appear following each call,
* see graphs of API usage, and
* inspect buffers.

Linux users can install it from their package manager, for example:

sudo apt install apitrace-tracers apitrace-gui

Windows users can [http://people.freedesktop.org/~jrfonseca/apitrace/ download a build].

==General Tips==

===Miscellaneous===

* To stress test the engine's ability to display a large number of buildables, set <code>g_humanBuildPoints</code> or <code>g_alienBuildPoints</code> to as high as you wish; this will allow you to build as much as you please.
* To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular <code>.pk3</code> archive), use the <code>\which</code> command with the relative path to the asset as an argument, such as <code>\which models/buildables/acid_tube/acid_tube.md5mesh</code>. Note that <code>which</code> accepts both forward- and backslashes regardless of platform.

===Working with packages===

To combine all packages together, at a Bash shell:

$ cd [[Game locations|<var>data directory</var>]]/pkg; mkdir tmp; for pk3 in pak{{0..9},A}.pk3; do unzip -o $pk3 -d tmp; done

(If there are additional <code>pak*</code> files (e.g., <code>pakB.pk3</code>), edit the pattern accordingly (e.g., to <code>pak{{0..9},{A..B}}.pk3</code>.)

This will place the cumulative contents (i.e., as the engine would see them) of all the <code>pak*.pk3</code> archives into a new <code>tmp/</code> directory in your data directory.

==Viewing Runtime Information==

The engine and game logic provide a number of commands for viewing information about its current state.

===Common Engine Functionality===

* <code>developer</code> — Set this to a true value (e.g., <code>1</code>) to enable displaying debugging information and the like.
* <code>fs_debug</code> — Set this to a true value (e.g., <code>1</code>) to enable filesystem debugging.
* <code>meminfo</code> — Display current memory usage.
* <code>fs_referencedList</code> —
* <code>fs_openedList</code> — List currently open files.

===Renderer===

* <code>fbolist</code> — List all frame buffer objects.
* <code>vbolist</code> — List all vertex buffer objects.

===Gamelogic===

* <code>entityList</code> —


==Testing materials and textures==

See {{Subpage|Materials}}.

==Testing maps==

See {{Subpage|Maps}}.

==Testing models==

See {{Subpage|Models}}.

==Reporting bugs==

Please see the [[Bug_reporting|bug reporting]] page.

Static Analysis

2022-11-06T09:08:01Z

Afontain:

{{OutOfDate}}

==What is static analysis?==

Static code analysis is a technique to identify potential faults and vulnerabilities in software without actually running the code. Static analysis software will examine the code itself to identify possible problem locations, then work backwards to identify how those could be reached. John Carmack, founder of id Software, has written an article [http://www.altdevblogaday.com/2011/12/24/static-code-analysis/ detailing the benefits of the technique].

==Xcode==

To use Xcode 4 to perform static analysis of the code, first follow the [[Compiling_the_source#Mac_OS_X|Xcode compilation instructions]], then in Xcode, select "Analyze". The process will take considerably longer than just compiling the source, so be patient.

Static Analysis

2022-11-06T09:07:47Z

Afontain: Move text that was on the Testing page (https://wiki.unvanquished.net/index.php?title=Testing)

{{OutOfDate}}
=Static Analysis=

==What is static analysis?==

Static code analysis is a technique to identify potential faults and vulnerabilities in software without actually running the code. Static analysis software will examine the code itself to identify possible problem locations, then work backwards to identify how those could be reached. John Carmack, founder of id Software, has written an article [http://www.altdevblogaday.com/2011/12/24/static-code-analysis/ detailing the benefits of the technique].

==Xcode==

To use Xcode 4 to perform static analysis of the code, first follow the [[Compiling_the_source#Mac_OS_X|Xcode compilation instructions]], then in Xcode, select "Analyze". The process will take considerably longer than just compiling the source, so be patient.

Formats/Behavior tree

2022-09-03T13:41:08Z

Afontain: /* List of functions (as of 0.52) */ update to 0.53.1

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== 0.53.1 ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* gesture
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide
* teleport

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>invert</code> keyword ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNINGcode> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.53.1) ===

* alertedToEnemy
* aliveTime
* baseRushScore
* buildingIsDamaged
* canEvolveTo
* class
* cvar
* directPathTo
* distanceTo
* goalBuildingType
* goalIsDead
* goalTeam
* goalType
* haveUpgrade
* haveWeapon
* healScore
* inAttackRange
* isVisible
* matchTime
* momentum
* percentAmmo
* percentHealth
* random
* skill
* stuckTime
* team
* teamateHasWeapon
* weapon

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Formats/Behavior tree

2022-09-03T13:39:53Z

Afontain: /* 0.53.1 */ remove the link to the webpage

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== 0.53.1 ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* gesture
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide
* teleport

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>invert</code> keyword ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNINGcode> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.52) ===

{ "alienMomentum", VALUE_INT, alienMomentum, 0 },
{ "humanMomentum", VALUE_INT, humanMomentum, 0 },
{ "alertedToEnemy", VALUE_INT, alertedToEnemy, 0 },
{ "baseRushScore", VALUE_FLOAT, baseRushScore, 0 },
{ "buildingIsDamaged", VALUE_INT, buildingIsDamaged, 0 },
{ "canEvolveTo", VALUE_INT, botCanEvolveTo, 1 },
{ "class", VALUE_INT, botClass, 0 },
{ "cvarFloat", VALUE_FLOAT, cvarFloat, 1 },
{ "cvarInt", VALUE_INT, cvarInt, 1 },
{ "directPathTo", VALUE_INT, directPathTo, 1 },
{ "distanceTo", VALUE_FLOAT, distanceTo, 1 },
{ "goalBuildingType", VALUE_INT, goalBuildingType, 0 },
{ "goalIsDead", VALUE_INT, goalDead, 0 },
{ "goalTeam", VALUE_INT, goalTeam, 0 },
{ "goalType", VALUE_INT, goalType, 0 },
{ "haveUpgrade", VALUE_INT, haveUpgrade, 1 },
{ "haveWeapon", VALUE_INT, haveWeapon, 1 },
{ "healScore", VALUE_FLOAT, healScore, 0 },
{ "inAttackRange", VALUE_INT, inAttackRange, 1 },
{ "isVisible", VALUE_INT, isVisible, 1 },
{ "percentAmmo", VALUE_FLOAT, percentAmmo, 0 },
{ "percentHealth", VALUE_FLOAT, percentHealth, 1 },
{ "random", VALUE_FLOAT, randomChance, 0 },
{ "skill", VALUE_INT, botSkill, 0 },
{ "stuckTime", VALUE_INT, stuckTime, 0 },
{ "team", VALUE_INT, botTeam, 0 },
{ "teamateHasWeapon", VALUE_INT, teamateHasWeapon, 1 },
{ "weapon", VALUE_INT, currentWeapon, 0 },

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Formats/Behavior tree

2022-09-03T13:38:51Z

Afontain: update action list

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== [[0.53.1]] ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* gesture
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide
* teleport

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>invert</code> keyword ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNINGcode> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.52) ===

{ "alienMomentum", VALUE_INT, alienMomentum, 0 },
{ "humanMomentum", VALUE_INT, humanMomentum, 0 },
{ "alertedToEnemy", VALUE_INT, alertedToEnemy, 0 },
{ "baseRushScore", VALUE_FLOAT, baseRushScore, 0 },
{ "buildingIsDamaged", VALUE_INT, buildingIsDamaged, 0 },
{ "canEvolveTo", VALUE_INT, botCanEvolveTo, 1 },
{ "class", VALUE_INT, botClass, 0 },
{ "cvarFloat", VALUE_FLOAT, cvarFloat, 1 },
{ "cvarInt", VALUE_INT, cvarInt, 1 },
{ "directPathTo", VALUE_INT, directPathTo, 1 },
{ "distanceTo", VALUE_FLOAT, distanceTo, 1 },
{ "goalBuildingType", VALUE_INT, goalBuildingType, 0 },
{ "goalIsDead", VALUE_INT, goalDead, 0 },
{ "goalTeam", VALUE_INT, goalTeam, 0 },
{ "goalType", VALUE_INT, goalType, 0 },
{ "haveUpgrade", VALUE_INT, haveUpgrade, 1 },
{ "haveWeapon", VALUE_INT, haveWeapon, 1 },
{ "healScore", VALUE_FLOAT, healScore, 0 },
{ "inAttackRange", VALUE_INT, inAttackRange, 1 },
{ "isVisible", VALUE_INT, isVisible, 1 },
{ "percentAmmo", VALUE_FLOAT, percentAmmo, 0 },
{ "percentHealth", VALUE_FLOAT, percentHealth, 1 },
{ "random", VALUE_FLOAT, randomChance, 0 },
{ "skill", VALUE_INT, botSkill, 0 },
{ "stuckTime", VALUE_INT, stuckTime, 0 },
{ "team", VALUE_INT, botTeam, 0 },
{ "teamateHasWeapon", VALUE_INT, teamateHasWeapon, 1 },
{ "weapon", VALUE_INT, currentWeapon, 0 },

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Formats/Behavior tree

2022-09-02T23:28:57Z

Afontain: Add "invert" decorator documentation

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== [[0.52]] ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>invert</code> keyword ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNINGcode> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.52) ===

{ "alienMomentum", VALUE_INT, alienMomentum, 0 },
{ "humanMomentum", VALUE_INT, humanMomentum, 0 },
{ "alertedToEnemy", VALUE_INT, alertedToEnemy, 0 },
{ "baseRushScore", VALUE_FLOAT, baseRushScore, 0 },
{ "buildingIsDamaged", VALUE_INT, buildingIsDamaged, 0 },
{ "canEvolveTo", VALUE_INT, botCanEvolveTo, 1 },
{ "class", VALUE_INT, botClass, 0 },
{ "cvarFloat", VALUE_FLOAT, cvarFloat, 1 },
{ "cvarInt", VALUE_INT, cvarInt, 1 },
{ "directPathTo", VALUE_INT, directPathTo, 1 },
{ "distanceTo", VALUE_FLOAT, distanceTo, 1 },
{ "goalBuildingType", VALUE_INT, goalBuildingType, 0 },
{ "goalIsDead", VALUE_INT, goalDead, 0 },
{ "goalTeam", VALUE_INT, goalTeam, 0 },
{ "goalType", VALUE_INT, goalType, 0 },
{ "haveUpgrade", VALUE_INT, haveUpgrade, 1 },
{ "haveWeapon", VALUE_INT, haveWeapon, 1 },
{ "healScore", VALUE_FLOAT, healScore, 0 },
{ "inAttackRange", VALUE_INT, inAttackRange, 1 },
{ "isVisible", VALUE_INT, isVisible, 1 },
{ "percentAmmo", VALUE_FLOAT, percentAmmo, 0 },
{ "percentHealth", VALUE_FLOAT, percentHealth, 1 },
{ "random", VALUE_FLOAT, randomChance, 0 },
{ "skill", VALUE_INT, botSkill, 0 },
{ "stuckTime", VALUE_INT, stuckTime, 0 },
{ "team", VALUE_INT, botTeam, 0 },
{ "teamateHasWeapon", VALUE_INT, teamateHasWeapon, 1 },
{ "weapon", VALUE_INT, currentWeapon, 0 },

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Formats/Behavior tree

2022-09-02T23:24:21Z

Afontain: Add "fallback" node documentation

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== [[0.52]] ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, STATUS_FAILURE is immediately returned if the timer's child node has already returned STATUS_FAILURE within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.52) ===

{ "alienMomentum", VALUE_INT, alienMomentum, 0 },
{ "humanMomentum", VALUE_INT, humanMomentum, 0 },
{ "alertedToEnemy", VALUE_INT, alertedToEnemy, 0 },
{ "baseRushScore", VALUE_FLOAT, baseRushScore, 0 },
{ "buildingIsDamaged", VALUE_INT, buildingIsDamaged, 0 },
{ "canEvolveTo", VALUE_INT, botCanEvolveTo, 1 },
{ "class", VALUE_INT, botClass, 0 },
{ "cvarFloat", VALUE_FLOAT, cvarFloat, 1 },
{ "cvarInt", VALUE_INT, cvarInt, 1 },
{ "directPathTo", VALUE_INT, directPathTo, 1 },
{ "distanceTo", VALUE_FLOAT, distanceTo, 1 },
{ "goalBuildingType", VALUE_INT, goalBuildingType, 0 },
{ "goalIsDead", VALUE_INT, goalDead, 0 },
{ "goalTeam", VALUE_INT, goalTeam, 0 },
{ "goalType", VALUE_INT, goalType, 0 },
{ "haveUpgrade", VALUE_INT, haveUpgrade, 1 },
{ "haveWeapon", VALUE_INT, haveWeapon, 1 },
{ "healScore", VALUE_FLOAT, healScore, 0 },
{ "inAttackRange", VALUE_INT, inAttackRange, 1 },
{ "isVisible", VALUE_INT, isVisible, 1 },
{ "percentAmmo", VALUE_FLOAT, percentAmmo, 0 },
{ "percentHealth", VALUE_FLOAT, percentHealth, 1 },
{ "random", VALUE_FLOAT, randomChance, 0 },
{ "skill", VALUE_INT, botSkill, 0 },
{ "stuckTime", VALUE_INT, stuckTime, 0 },
{ "team", VALUE_INT, botTeam, 0 },
{ "teamateHasWeapon", VALUE_INT, teamateHasWeapon, 1 },
{ "weapon", VALUE_INT, currentWeapon, 0 },

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

UI/Design

2022-07-07T01:03:36Z

Afontain: delete page

Humans

2021-11-23T14:09:54Z

Afontain:

{{InfoBoxStart | name = Human | image = Human standing.jpeg | caption = A fearless clone trooper.}}
{{InfoRow | caption = Health | value = 100 }}
{{InfoBoxEnd}}

==Tips==

* Go out in groups. Unlike aliens, humans have little chance of escaping if they meet an overwhelming force outside their base.

* If you have enough credits, buy at least a [[Light Armour|light armour]]. With it you can't be killed in a single hit, except by a [[tyrant]].

* Energy weapons ([[Las Gun|lasgun]], [[Pulse Rifle|pulse rifle]], [[Lucifer Cannon|Lucifer cannon]]) can also be recharged at the [[reactor]].

[[File:Exploding_Turret.png|thumb|center|Don't stay close to dead buildings: their explosion will hurt you.]]

* When keeping the "jump" key pressed while touching a wall, humans can "wall run", increasing their mobility.

* Humans, unlike aliens, can use ladders.

* Humans can "slide", whatever that mean (please update this if you know more).

* Medkit will progressively restore all the health you loosed at the moment you use it, in roughly 13s. Using it wisely will allow you to retreat safely, or to launch an attack at full health.

* Crouching reduces recoil with weapons. This is mostly (only?) useful for chaingun though, and makes you slower.

==Weapons==

{| class="wikitable spaced"
! Name
! Unlock
! Cost
! Ammo
! Damage
|-
| [[Blaster]]
| 0
| Free
| ∞
| 10 per second
|-
| [[Construction Kit]]
| 0
| Free
| -
| Used to build structures (cooldown ~6s).
|-
| [[SMG]]
| 0
| Free
| 30/6
| 62.5 per second, 150 per magazine.
|-
| [[Shotgun]]
| 0
| 150
| 8/3
| 55 per second, 440 per magazine.
|-
| [[Las Gun]]
| 0
| 250
| 200
| 45 per second, 1800 per magazine.
|-
| [[Mass Driver]]
| 0
| 350
| 6/4
| 40 per second, 240 per magazine.
|-
| [[Chaingun]]
| 0
| 400
| 300
| 68 per second, 1800 per magazine.
|-
| [[Pain Saw]]
| 1
| 100
| ∞
| 147 per second.
|-
| [[Flame Thrower]]
| 2
| 450
| 300
| 140 per second, 4200 per magazine.
|-
| [[Pulse Rifle]]
| 2
| 450
| 50/5
| 90 per second, 450 per magazine.
|-
| [[Lucifer Cannon]]
| 5
| 600
| 100
| Up to 265 per shot, 88 per second, 2650 per magazine.
|-
|}

==Armour==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! % of base damage (head/back/front/legs)
! walk speed (forward/backward/lateral) in game's units
! run speed (forward/backward/lateral) in game's units
! comment
|-
| [[Basic Armour]]
| 0
| Free
| 150/100/100/60
| 319/255/287
| 383/307/345
| -
|-
| [[Light Armour]]
| 0
| 200
| 80/50/35/20
| 319/255/287
| 383/307/345
| -
|-
| [[Medium Armour]]
| 3
| 300
| 60/35/30/20
| 319/255/287
| 367/294/331
| -
|-
| [[Battlesuit]]
| 4
| 400
| 40/20/20/15
| 319/255/287
| 367/294/331
| prevent the use of jetpacks or radars. Wearing Battlesuit reduces mobility, preventing the user to wallrun and slide.
|-
|}

Notes:

* Walk speed seems to never be affected.
* Only armor affect speeds. Probably same for stamina.
* Each armor class have a different impact on stamina reserves.
* Sufficient stamina reserves is needed to be able to jump.

==Backpacks==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Effects
|-
| [[Radar]]
| 1
| 100
| Communicates position of seen aliens to the team.
|-
| [[Jetpack|Jet Pack]]
| 2
| 120
| Allows the user to fly for short periods of time.
|-
|}

==Grenades==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Damage
|-
| [[Firebomb]]
| 2
| 200
| 50 at epicenter, sets alien structures on fire.
|-
| [[Grenade]]
| 4
| 250
| 310 at epicenter.
|-
|}

==Buildables==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Health
| Regen
| Time to heal
! Description
|-
| [[Reactor]]
| 0
| Free
| 930
| 15
| 62
| Keep everything around the map powered. If it goes down, you turrets will quickly get destroyed and you can't use the armory or the medistation.
|-
| [[Telenode]]
| 0
| 10
| 310
| 10
| 31
| Allows humans to enter the battle arena. Defeat is imminent upon destruction of the last telenode.
|-
| [[Armory]]
| 0
| 8
| 420
| 10
| 42
| Allows humans to buy weapons and upgrades.
|-
| [[Medistation]]
| 0
| 8
| 190
| 5
| 38
| Restores health and issues medkits. Can only be used by one human at a time.
|-
| [[Machinegun Turret]]
| 0
| 10
| 250
| 5
| 50
| Short-range defensive structure. Very powerful area denial weapon.
|-
| [[Rocket Pod]]
| 1
| 10
| 250
| 5
| 50
| Long-range defensive structure. Fires missiles that track ennemies every ~3s but won't shot at close range.
|-
| [[Drill]]
| 0
| 4
| 200
| 5
| 40
| Drills for materials.
|-
|}

[[Category:Humans]]

Humans

2021-11-23T14:09:26Z

Afontain: Rework tips

{{InfoBoxStart | name = Human | image = Human standing.jpeg | caption = A fearless clone trooper.}}
{{InfoRow | caption = Health | value = 100 }}
{{InfoBoxEnd}}

==Tips==

* Go out in groups. Unlike aliens, humans have little chance of escaping if they meet an overwhelming force outside their base.

* If you have enough credits, buy at least a [[Light Armour|light armour]]. With it you can't be killed in a single hit, except by a [[tyrant]].

* Energy weapons ([[Las Gun|lasgun]], [[Pulse Rifle|pulse rifle]], [[Lucifer Cannon|Lucifer cannon]]) can also be recharged at the [[reactor]].

[[File:Exploding_Turret.png|thumb|center|Don't stay close to dead buildings: their explosion will hurt you.]]

* When keeping the "jump" key pressed while touching a wall, humans can "wall run", increasing their mobility.

* Humans, unlike aliens, can use ladders.



* Medkit will progressively restore all the health you loosed at the moment you use it, in roughly 13s. Using it wisely will allow you to retreat safely, or to launch an attack at full health.

* Crouching reduces recoil with weapons. This is mostly (only?) useful for chaingun though, and makes you slower.

==Weapons==

{| class="wikitable spaced"
! Name
! Unlock
! Cost
! Ammo
! Damage
|-
| [[Blaster]]
| 0
| Free
| ∞
| 10 per second
|-
| [[Construction Kit]]
| 0
| Free
| -
| Used to build structures (cooldown ~6s).
|-
| [[SMG]]
| 0
| Free
| 30/6
| 62.5 per second, 150 per magazine.
|-
| [[Shotgun]]
| 0
| 150
| 8/3
| 55 per second, 440 per magazine.
|-
| [[Las Gun]]
| 0
| 250
| 200
| 45 per second, 1800 per magazine.
|-
| [[Mass Driver]]
| 0
| 350
| 6/4
| 40 per second, 240 per magazine.
|-
| [[Chaingun]]
| 0
| 400
| 300
| 68 per second, 1800 per magazine.
|-
| [[Pain Saw]]
| 1
| 100
| ∞
| 147 per second.
|-
| [[Flame Thrower]]
| 2
| 450
| 300
| 140 per second, 4200 per magazine.
|-
| [[Pulse Rifle]]
| 2
| 450
| 50/5
| 90 per second, 450 per magazine.
|-
| [[Lucifer Cannon]]
| 5
| 600
| 100
| Up to 265 per shot, 88 per second, 2650 per magazine.
|-
|}

==Armour==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! % of base damage (head/back/front/legs)
! walk speed (forward/backward/lateral) in game's units
! run speed (forward/backward/lateral) in game's units
! comment
|-
| [[Basic Armour]]
| 0
| Free
| 150/100/100/60
| 319/255/287
| 383/307/345
| -
|-
| [[Light Armour]]
| 0
| 200
| 80/50/35/20
| 319/255/287
| 383/307/345
| -
|-
| [[Medium Armour]]
| 3
| 300
| 60/35/30/20
| 319/255/287
| 367/294/331
| -
|-
| [[Battlesuit]]
| 4
| 400
| 40/20/20/15
| 319/255/287
| 367/294/331
| prevent the use of jetpacks or radars. Wearing Battlesuit reduces mobility, preventing the user to wallrun and slide.
|-
|}

Notes:

* Walk speed seems to never be affected.
* Only armor affect speeds. Probably same for stamina.
* Each armor class have a different impact on stamina reserves.
* Sufficient stamina reserves is needed to be able to jump.

==Backpacks==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Effects
|-
| [[Radar]]
| 1
| 100
| Communicates position of seen aliens to the team.
|-
| [[Jetpack|Jet Pack]]
| 2
| 120
| Allows the user to fly for short periods of time.
|-
|}

==Grenades==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Damage
|-
| [[Firebomb]]
| 2
| 200
| 50 at epicenter, sets alien structures on fire.
|-
| [[Grenade]]
| 4
| 250
| 310 at epicenter.
|-
|}

==Buildables==

{| class="wikitable spaced"
|-
! Name
! Unlock
! Cost
! Health
| Regen
| Time to heal
! Description
|-
| [[Reactor]]
| 0
| Free
| 930
| 15
| 62
| Keep everything around the map powered. If it goes down, you turrets will quickly get destroyed and you can't use the armory or the medistation.
|-
| [[Telenode]]
| 0
| 10
| 310
| 10
| 31
| Allows humans to enter the battle arena. Defeat is imminent upon destruction of the last telenode.
|-
| [[Armory]]
| 0
| 8
| 420
| 10
| 42
| Allows humans to buy weapons and upgrades.
|-
| [[Medistation]]
| 0
| 8
| 190
| 5
| 38
| Restores health and issues medkits. Can only be used by one human at a time.
|-
| [[Machinegun Turret]]
| 0
| 10
| 250
| 5
| 50
| Short-range defensive structure. Very powerful area denial weapon.
|-
| [[Rocket Pod]]
| 1
| 10
| 250
| 5
| 50
| Long-range defensive structure. Fires missiles that track ennemies every ~3s but won't shot at close range.
|-
| [[Drill]]
| 0
| 4
| 200
| 5
| 40
| Drills for materials.
|-
|}

[[Category:Humans]]

File:Exploding Turret.png

2021-11-23T14:01:27Z

Afontain: Human turret exploding

== Summary ==
Human turret exploding
== Licencing ==
{{licenses/cc-by-sa-3.0}}

Drill

2021-11-07T23:45:16Z

Afontain:

{{InfoBoxStart | name = Drill | image = Drill.png | caption = Why hasn't the floor collapsed yet?}}
{{InfoRow | caption = Cost | value = 0 Credits }}
{{InfoRow | caption = Unlock | value = - }}
{{InfoRow | caption = Health | value = 200 }}
{{InfoRow | caption = Build Time | value = 10 seconds }}
{{InfoBoxEnd}}

Drills the ground for materials.

== Tips ==

* Spread them apart for maximum mining efficiency. Keep in mind that two drills right next to each other will mine out less material than a single drill.

* Defend your drills well. If a drill is destroyed, you'll lose a portion of your stored material.

* If you feel a forward base with a drill in it isn't going to last for much longer, deconstruct the buildables that are worth money to prevent the loss of material.

[[File:Unvanquished 2021-11-Light armor with lasgun.jpg]]

[[File:2021-11-Drills too close.jpg]]

When Drills and [[Leech|Leeches]] are close together, they annihilates themself.
# Only with the [[Construction_Kit|Construction Kit]] you can see that they consume BP instead generate power.

It's the same for a Drill near a [[Leech|Leech]].

[[Category:Humans]]

Formats/Behavior tree

2021-11-01T22:02:54Z

Afontain: /* The return keyword */

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node (I am not sure when exactly evaluation ends). An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* at most one node, leaf, block start or block end per line
* empty lines are accepted
* comments can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line (TODO: verify).
* comments can not be nested
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* spaces and tabulations are meaningless
* strings start and end with a double quote <code>"</code>
* keywords are reserved (TODO: verify, but even if wrong, better avoid their use)
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place.
It is unsure if this is just an inclusion of if the subtree is parsed and stored individually.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== [[0.52]] ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>concurrent</code> keyword ==

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>.
Differences with sequence:

* <code>STATUS_RUNNING</code> does not trigger a return
* Returns either <code>STATUS_SUCCESS</code> except if one child failed <code>STATUS_FAILURE</code>.

Notes:

* if 2 tasks were previously in <code>STATUS_RUNNING</code> and the 1st returns <code>STATUS_FAILURE</code>, concurrent returns immediately.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

Differences with concurrent:

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Does not restart from last <code>STATUS_RUNNING</code>.

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* timer

== The <code>return</code> keyword ==

Force children nodes to return a specific value

== The <code>timer</code> keyword ==

On encountering a <code>timer( N )</code> node, STATUS_FAILURE is immediately returned if the timer's child node has already returned STATUS_FAILURE within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "! "
* "< "
* "<="
* "> "
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.52) ===

{ "alienMomentum", VALUE_INT, alienMomentum, 0 },
{ "humanMomentum", VALUE_INT, humanMomentum, 0 },
{ "alertedToEnemy", VALUE_INT, alertedToEnemy, 0 },
{ "baseRushScore", VALUE_FLOAT, baseRushScore, 0 },
{ "buildingIsDamaged", VALUE_INT, buildingIsDamaged, 0 },
{ "canEvolveTo", VALUE_INT, botCanEvolveTo, 1 },
{ "class", VALUE_INT, botClass, 0 },
{ "cvarFloat", VALUE_FLOAT, cvarFloat, 1 },
{ "cvarInt", VALUE_INT, cvarInt, 1 },
{ "directPathTo", VALUE_INT, directPathTo, 1 },
{ "distanceTo", VALUE_FLOAT, distanceTo, 1 },
{ "goalBuildingType", VALUE_INT, goalBuildingType, 0 },
{ "goalIsDead", VALUE_INT, goalDead, 0 },
{ "goalTeam", VALUE_INT, goalTeam, 0 },
{ "goalType", VALUE_INT, goalType, 0 },
{ "haveUpgrade", VALUE_INT, haveUpgrade, 1 },
{ "haveWeapon", VALUE_INT, haveWeapon, 1 },
{ "healScore", VALUE_FLOAT, healScore, 0 },
{ "inAttackRange", VALUE_INT, inAttackRange, 1 },
{ "isVisible", VALUE_INT, isVisible, 1 },
{ "percentAmmo", VALUE_FLOAT, percentAmmo, 0 },
{ "percentHealth", VALUE_FLOAT, percentHealth, 1 },
{ "random", VALUE_FLOAT, randomChance, 0 },
{ "skill", VALUE_INT, botSkill, 0 },
{ "stuckTime", VALUE_INT, stuckTime, 0 },
{ "team", VALUE_INT, botTeam, 0 },
{ "teamateHasWeapon", VALUE_INT, teamateHasWeapon, 1 },
{ "weapon", VALUE_INT, currentWeapon, 0 },

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)
* double (Unboxed only)
* token (Boxed only, either a <code>TT_STRING</code>, a float or an int...)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Modder Documentation: classes .attr.cfg

2021-10-25T16:57:08Z

Afontain:

Here are some of the fields present in an <code>pkg/unvanquished_src.dpkdir/configs/classes/'''''class'''''.attr.cfg</code>.

== Metadata ==
description "null"
icon "null"
fovCvar "cg_fov_human"
team human
unlockThreshold 0

TODO: document

== Health ==

here's an ''attr.cfg'' extract:
health 100
fallDamage 1.0
regen 0.0

in it we see:
* <code>health</code> how many hp the form have (note that this doesn't work for humans as of 0.52.1)
* <code>fallDamage</code> how much hp is lost when falling. 1.0 is "as much as a normal human". Note that it is also affected by armor if armor is worn ("nonloc" damage)
* <code>regen</code> how many hp/second are recovered when the creature hasn't been hurt for some time

== View ==

here's an ''attr.cfg'' extract:
//View parameters
fov 90
bob 0.001
bobCycle 1.1
stepTime 100

TODO: explain

== Movement and mass parameters ==

here's an ''attr.cfg'' extract:
// Physics parameters
speed 1.1
sprintMod 1.2
acceleration 10.0
airAcceleration 1.0
friction 7
stopSpeed 100.0
jumpMagnitude 170.0

in it we see:
* <code>speed</code> the maximum speed (relative: 1.0 is the speed of a naked human)
* <code>sprintMod</code> (only makes sense for humans) how much sprinting accelerates (relative: 2.0 is the double of the normal <code>speed</code>)
* <code>acceleration</code> how fast can you change speed while touching the ground
* <code>airAcceleration</code> how fast can you change speed while in the air: you'll notice that a marauder can easily change direction on the ground, but has more trouble steering in the air.
* <code>friction</code> how fast is speed lost. Note that if it is high (in the hundreds), it will actually limit your max speed noticeably.
* <code>stopSpeed</code> means the speed under which the speed will be set to 0.
* <code>jumpMagnitude</code> is how high you can jump.

== Abilities ==
here are some possible values (''attr.cfg'' extract):
// Abilities
takesFallDamage
canUseLadders
wallRunner
slider
alienSense
fovWarps

TODO: explain

== Stamina (humans) ==
here's an ''attr.cfg'' extract:
// Stamina (per action or second)
staminaJumpCost 3750
staminaSprintCost 750
staminaJogRestore 750
staminaWalkRestore 2250
staminaStopRestore 4500

in it we see:
* <code>staminaJumpCost</code> how much stamina you spend for a jump
* <code>staminaSprintCost</code> how much stamina you spend per second when running
* <code>staminaJogRestore</code> how fast you recover your stamina (amount per second) '''while walking but not running'''
* <code>staminaWalkRestore</code> how fast you recover your stamina (amount per second) '''while walking slowly or crouching'''
* <code>staminaStopRestore</code> how fast you recover your stamina (amount per second) when not moving

== Miscs ==
here's an ''attr.cfg'' extract:
// Misc
cost 200
buildDistance 110.0

in it we see:
* <code>cost</code> how much it costs to buy the class or the object. From 0 to 2000 (for all teams)
* <code>buildDistance</code> the maximum distance this form can build (assuming a suitable weapon and class)

Modder Documentation: classes .attr.cfg

2021-10-25T16:56:45Z

Afontain:

Here are some of the fields present in an <code>pkg/unvanquished_src.dpkdir/configs/classes/'''''class'''''.attr.cfg</code>.

== Metadata ==
description "null"
icon "null"
fovCvar "cg_fov_human"
team human
unlockThreshold 0

TODO: document

== Health ==

here's an ''attr.cfg'' extract:
health 100
fallDamage 1.0
regen 0.0

* <code>health</code> how many hp the form have (note that this doesn't work for humans as of 0.52.1)
* <code>fallDamage</code> how much hp is lost when falling. 1.0 is "as much as a normal human". Note that it is also affected by armor if armor is worn ("nonloc" damage)
* <code>regen</code> how many hp/second are recovered when the creature hasn't been hurt for some time

== View ==

here's an ''attr.cfg'' extract:
//View parameters
fov 90
bob 0.001
bobCycle 1.1
stepTime 100

TODO: explain

== Movement and mass parameters ==

here's an ''attr.cfg'' extract:
// Physics parameters
speed 1.1
sprintMod 1.2
acceleration 10.0
airAcceleration 1.0
friction 7
stopSpeed 100.0
jumpMagnitude 170.0

in it we see:
* <code>speed</code> the maximum speed (relative: 1.0 is the speed of a naked human)
* <code>sprintMod</code> (only makes sense for humans) how much sprinting accelerates (relative: 2.0 is the double of the normal <code>speed</code>)
* <code>acceleration</code> how fast can you change speed while touching the ground
* <code>airAcceleration</code> how fast can you change speed while in the air: you'll notice that a marauder can easily change direction on the ground, but has more trouble steering in the air.
* <code>friction</code> how fast is speed lost. Note that if it is high (in the hundreds), it will actually limit your max speed noticeably.
* <code>stopSpeed</code> means the speed under which the speed will be set to 0.
* <code>jumpMagnitude</code> is how high you can jump.

== Abilities ==
here are some possible values (''attr.cfg'' extract):
// Abilities
takesFallDamage
canUseLadders
wallRunner
slider
alienSense
fovWarps

TODO: explain

== Stamina (humans) ==
here's an ''attr.cfg'' extract:
// Stamina (per action or second)
staminaJumpCost 3750
staminaSprintCost 750
staminaJogRestore 750
staminaWalkRestore 2250
staminaStopRestore 4500

in it we see:
* <code>staminaJumpCost</code> how much stamina you spend for a jump
* <code>staminaSprintCost</code> how much stamina you spend per second when running
* <code>staminaJogRestore</code> how fast you recover your stamina (amount per second) '''while walking but not running'''
* <code>staminaWalkRestore</code> how fast you recover your stamina (amount per second) '''while walking slowly or crouching'''
* <code>staminaStopRestore</code> how fast you recover your stamina (amount per second) when not moving

== Miscs ==
here's an ''attr.cfg'' extract:
// Misc
cost 200
buildDistance 110.0

in it we see:
* <code>cost</code> how much it costs to buy the class or the object. From 0 to 2000 (for all teams)
* <code>buildDistance</code> the maximum distance this form can build (assuming a suitable weapon and class)

Modder Documentation: classes .attr.cfg

2021-10-25T16:48:52Z

Afontain:

Here are some of the fields present in an <code>pkg/unvanquished_src.dpkdir/configs/classes/'''''class'''''.attr.cfg</code>.

== Metadata ==
description "null"
icon "null"
fovCvar "cg_fov_human"
team human
unlockThreshold 0

TODO: document

== Health ==

here's an ''attr.cfg'' extract:
health 100
fallDamage 1.0
regen 0.0

this should be clear enough

== View ==

here's an ''attr.cfg'' extract:
//View parameters
fov 90
bob 0.001
bobCycle 1.1
stepTime 100

TODO: explain

== Movement and mass parameters ==

here's an ''attr.cfg'' extract:
// Physics parameters
speed 1.1
sprintMod 1.2
acceleration 10.0
airAcceleration 1.0
friction 7
stopSpeed 100.0
jumpMagnitude 170.0

in it we see:
* <code>speed</code> the maximum speed (relative: 1.0 is the speed of a naked human)
* <code>sprintMod</code> (only makes sense for humans) how much sprinting accelerates (relative: 2.0 is the double of the normal <code>speed</code>)
* <code>acceleration</code> how fast can you change speed while touching the ground
* <code>airAcceleration</code> how fast can you change speed while in the air: you'll notice that a marauder can easily change direction on the ground, but has more trouble steering in the air.
* <code>friction</code> how fast is speed lost. Note that if it is high (in the hundreds), it will actually limit your max speed noticeably.
* <code>stopSpeed</code> means the speed under which the speed will be set to 0.
* <code>jumpMagnitude</code> is how high you can jump.

== Abilities ==
here are some possible values (''attr.cfg'' extract):
// Abilities
takesFallDamage
canUseLadders
wallRunner
slider
alienSense
fovWarps

TODO: explain

== Stamina (humans) ==
here's an ''attr.cfg'' extract:
// Stamina (per action or second)
staminaJumpCost 3750
staminaSprintCost 750
staminaJogRestore 750
staminaWalkRestore 2250
staminaStopRestore 4500

in it we see:
* <code>staminaJumpCost</code> how much stamina you spend for a jump
* <code>staminaSprintCost</code> how much stamina you spend per second when running
* <code>staminaJogRestore</code> how fast you recover your stamina (amount per second) '''while walking but not running'''
* <code>staminaWalkRestore</code> how fast you recover your stamina (amount per second) '''while walking slowly or crouching'''
* <code>staminaStopRestore</code> how fast you recover your stamina (amount per second) when not moving

== Miscs ==
here's an ''attr.cfg'' extract:
// Misc
cost 200
buildDistance 110.0

in it we see:
* <code>cost</code> how much it costs to buy the class or the object. From 0 to 2000 (for all teams)
* <code>buildDistance</code> the maximum distance this form can build (assuming a suitable weapon and class)

Modder Documentation: classes .attr.cfg

2021-10-25T16:28:51Z

Afontain: created

Here are some of the fields present in an <code>pkg/unvanquished_src.dpkdir/configs/classes/'''''form'''''.attr.cfg</code>.

== Metadata ==
description "null"
icon "null"
fovCvar "cg_fov_human"
team human
unlockThreshold 0

TODO: document

== Health ==

here's an ''attr.cfg'' extract:
health 100
fallDamage 1.0
regen 0.0

this should be clear enough

== View ==

here's an ''attr.cfg'' extract:
//View parameters
fov 90
bob 0.001
bobCycle 1.1
stepTime 100

TODO: explain

== Movement and mass parameters ==

here's an ''attr.cfg'' extract:
// Physics parameters
speed 1.1
sprintMod 1.2
acceleration 10.0
airAcceleration 1.0
friction 7
stopSpeed 100.0
jumpMagnitude 170.0

in it we see:
* <code>speed</code> the maximum speed (relative: 1.0 is the speed of a naked human)
* <code>sprintMod</code> (only makes sense for humans) how much sprinting accelerates (relative: 2.0 is the double of the normal <code>speed</code>)
* <code>acceleration</code> how fast can you change speed while touching the ground
* <code>airAcceleration</code> how fast can you change speed while in the air: you'll notice that a marauder can easily change direction on the ground, but has more trouble steering in the air.
* <code>friction</code> how fast is speed lost. Note that if it is high (in the hundreds), it will actually limit your max speed noticeably.
* <code>stopSpeed</code> means the speed under which the speed will be set to 0.
* <code>jumpMagnitude</code> is how high you can jump.

== Abilities ==
here are some possible values (''attr.cfg'' extract):
// Abilities
takesFallDamage
canUseLadders
wallRunner
slider
alienSense
fovWarps

TODO: explain

== Stamina (humans) ==
here's an ''attr.cfg'' extract:
// Stamina (per action or second)
staminaJumpCost 3750
staminaSprintCost 750
staminaJogRestore 750
staminaWalkRestore 2250
staminaStopRestore 4500

in it we see:
* <code>staminaJumpCost</code> how much stamina you spend for a jump
* <code>staminaSprintCost</code> how much stamina you spend per second when running
* <code>staminaJogRestore</code> how fast you recover your stamina (amount per second) '''while walking but not running'''
* <code>staminaWalkRestore</code> how fast you recover your stamina (amount per second) '''while walking slowly or crouching'''
* <code>staminaStopRestore</code> how fast you recover your stamina (amount per second) when not moving

== Miscs ==
here's an ''attr.cfg'' extract:
// Misc
cost 200
buildDistance 110.0

in it we see:
* <code>cost</code> how much it costs to buy the class or the object. From 0 to 2000 (for all teams)
* <code>buildDistance</code> the maximum distance this form can build (assuming a suitable weapon and class)

Compatibility

2021-10-17T20:18:31Z

Afontain: /* Daemon */

= Inter-module compatibility =

Unvanquished has many software components: engine binaries, based on the Daemon repository (client and server); gamelogic binaries, based on the Unvanquished repository (cgame and sgame); and various other files shipped in DPKs, which may be used by any of the binaries. Currently, all components are on a single release cycle. A given user normally has only one version of the client installed, but different servers may distribute differing versions of the other components via the auto-download mechanism. This means many different combinations of versions of the components are possible. It can be difficult to reason about which combinations will work correctly, and even which combinations ought to be allowed.

In the rest of this article, "Unvanquished" refers to the eponymous Git repository, not the game.

== Desired use cases ==
=== Use cases we want to support ===
* Develop on next-release branch (e.g. <code>0.52.0/sync</code>) of all repos (Daemon, Unvanquished, unvanquished_src.dpkdir)
* Develop on master branch of all repos
* Build client from laster master and connect to latest-release servers We should be able to play with everyone on a client with the latest bug fixes.
* Build server from latest master and host with latest-release DPKs Likewise with a server.
* Build sgame from master and use it with latest-release cgame Server owners could ship sgame bug fixes without requiring a download.
* Develop Unvanquished on master, using latest-release DPKs Development for simple cases should be accessible, not requiring <code>-pakpath</code> flags etc.

=== Use cases we don't really care about ===
* Using unvanquished_src.dpkdir from master with latest-release gamelogic
* Using a cgame built from an older commit than the sgame

== Per-repository guidance ==

=== Daemon ===

Adding or removing an IPC call must be done on the next-release branch.

When developing Daemon master, you need to keep in mind compatibility with both the latest release and the current master of the gamelogic.

=== Unvanquished ===

Try to keep the submodule pointers to Daemon and unvanquished_src.dpkdir at commits which are compatible with the Unvanquished commit containing them. We want to get a harmonious set of components when we do a recursive checkout of some Unvanquished commit.

In addition to compatibility with other repos, it is necessary to consider compatibility between cgame and sgame. For example, if you want to add a field to the <code>playerState_t</code> netcode <ref>It is only possible to change this without rebuilding the engine starting from version 0.52.</ref>, you should do that on the next-release branch. (But if you are a mod developer, you may add fields at any time, provided you ship a cgame.)

=== unvanquished_src.dpkdir ===

When developing on master, you just need to keep it working with the master of Unvanquished. The expectation is that server owners who are shipping a cutting-edge version of this repo should also rebuild the gamelogic.

=== Other *.dkpdir repos ===

There isn't a lot of precedent here. Probably it's best to do anything except bug fixes on a next-release branch. If possible, we want to avoid any situation where developers are required to use any unreleased stuff from these to get a working setup.

== Open questions ==

Should gameplay changes be encouraged on the Unvanquished master branch, as long as they follow compatibility guidelines? Or should those stick to the next-release branch?

On one hand, it might be nice to build the gamelogic from master as a way to test the latest gameplay changes. On the other hand, many gameplay changes will require cgame or pak changes to work; perhaps it is better to keep all gameplay changes together on the next-release branch. We could consider dropping the use-case "Build sgame from master and use it with latest-release cgame" to allow a greater share of gameplay changes on master (ones which modify both sgame and cgame, not just sgame), but we should still forbid changes to master that require modification of unvanquished_src.dpkdir or other paks, since it inconveniences developers.

<hr>

File:Chaingun.png

2021-07-29T13:39:07Z

Afontain: Afontain uploaded a new version of File:Chaingun.png

Chaingun

2021-07-29T13:36:56Z

Afontain:

{{InfoBoxStart | name = Chaingun | image = Chaingun.png | caption = Possibly the biggest gun of all.}}
{{InfoRow | caption = Cost | value = 400 credits }}
{{InfoRow | caption = Unlock | value = - }}
{{InfoRow | caption = Ammo | value = 300 }}
{{InfoRow | caption = Energy Weapon | value = No }}
{{InfoRow | caption = Damage | value = 6 }}
{{InfoRow | caption = Damage Per Second | value = 68 }}
{{InfoRow | caption = Damage Per Magazine | value = 1800 }}
{{InfoRow | caption = Fire Rate | value = 11 per second }}
{{InfoBoxEnd}}

The chaingun provides a high rate of fire, moderate damage per shot, and a large ammo capacity. It fires many weak shots at a rapid pace, and causes enough knockback to send your view flying all over the place if you're not crouching or wearing a battlesuit. Absolutely fantastic against tyrants and opponents that keep moving around.

==Tips==

* Stay close to your opponent, as the chaingun is far too inaccurate for long range combat.
* crouching helps accuracy, but makes head more vulnerable

[[Category:Humans]]

Las Gun

2021-07-29T13:14:19Z

Afontain: battery pack is dead

{{InfoBoxStart | name = Las Gun | image = Lasgun.jpg | caption = Sanest of them all.}}
{{InfoRow | caption = Cost | value = 250 credits }}
{{InfoRow | caption = Unlock | value = - }}
{{InfoRow | caption = Ammo | value = 200 }}
{{InfoRow | caption = Energy Weapon | value = Yes }}
{{InfoRow | caption = Damage | value = 9 }}
{{InfoRow | caption = Damage Per Second | value = 45 }}
{{InfoRow | caption = Damage Per Magazine | value = 1800 }}
{{InfoRow | caption = Fire Rate | value = 5 per second }}
{{InfoBoxEnd}}

The first energy weapon available. It functions much like a vastly improved rifle, at the cost of a decline in the rate of fire.

==Tips==

* Use this against alien bases. It's great! Park yourself in a corner where you aren't being acid tubed, and fire away at eggs while your teammates shoot at other things.

* Don't be afraid to duel with it, as long as you're good at keeping range. You don't need to make up for accuracy with this weapon, so it works fine at any range. Keep circling and firing until they're dead.

* Use this in groups, much like the rifle. It'll make up for your lower firing rate, and the constant shooting will scare most aliens off.

==Background==

Fulfilling a similar role to the more common rifle, the lasgun possesses several advantages of its own. Unlike its bullet-churning cousin, the weapon possesses a single large power cell, eliminating the need to reload and allowing its user to keep a constant rate of fire for as long as the cell is charged and the trigger is held. Each “shot” is a pinpoint accurate, coherent burst of high frequency electromagnetic radiation, invisible to human eyes but readily felt as a sudden shock of intense heat that burns flesh with ease. The amplifier must be cooled down between shots, and while this is accomplished in a fraction of a second, there is still an easily noticed delay in comparison to the rifle.

Although superior to the rifle in most regards, the lasgun’s components are far more expensive to manufacture, and thus it is typically entrusted to soldiers that show some degree of marksmanship and survivability above that of a new recruit. Although eclipsed by the other energy weapons in terms of damage output, it is highly regarded as the most efficient weapon in the human arsenal.

[[Category:Humans]]

Las Gun

2021-07-29T13:13:20Z

Afontain: lasgun can't reload

{{InfoBoxStart | name = Las Gun | image = Lasgun.jpg | caption = Sanest of them all.}}
{{InfoRow | caption = Cost | value = 250 credits }}
{{InfoRow | caption = Unlock | value = - }}
{{InfoRow | caption = Ammo | value = 200 }}
{{InfoRow | caption = Energy Weapon | value = Yes }}
{{InfoRow | caption = Damage | value = 9 }}
{{InfoRow | caption = Damage Per Second | value = 45 }}
{{InfoRow | caption = Damage Per Magazine | value = 1800 }}
{{InfoRow | caption = Fire Rate | value = 5 per second }}
{{InfoBoxEnd}}

The first energy weapon available. It functions much like a vastly improved rifle, at the cost of a decline in the rate of fire.

==Tips==

* Use this against alien bases. It's great! Park yourself in a corner where you aren't being acid tubed, and fire away at eggs while your teammates shoot at other things.

* Don't be afraid to duel with it, as long as you're good at keeping range. You don't need to make up for accuracy with this weapon, so it works fine at any range. Keep circling and firing until they're dead.

* Use this in groups, much like the rifle. It'll make up for your lower firing rate, and the constant shooting will scare most aliens off.

==Background==

Fulfilling a similar role to the more common rifle, the lasgun possesses several advantages of its own. Unlike its bullet-churning cousin, the weapon possesses a single large power cell, eliminating the need to reload and allowing its user to keep a constant rate of fire for as long as the cell is charged and the trigger is held. Each “shot” is a pinpoint accurate, coherent burst of high frequency electromagnetic radiation, invisible to human eyes but readily felt as a sudden shock of intense heat that burns flesh with ease. The amplifier must be cooled down between shots, and while this is accomplished in a fraction of a second, there is still an easily noticed delay in comparison to the rifle.

Although superior to the rifle in most regards, the lasgun’s components are far more expensive to manufacture, and thus it is typically entrusted to soldiers that show some degree of marksmanship and survivability above that of a new recruit. It may be connected to a battery pack, providing even more energy to the power cell. Although eclipsed by the other energy weapons in terms of damage output, it is highly regarded as the most efficient weapon in the human arsenal.

[[Category:Humans]]

File:Lasgun.jpg

2021-07-29T13:11:10Z

Afontain: Afontain uploaded a new version of File:Lasgun.jpg

Lasgun.

Light Armour

2021-07-29T12:56:13Z

Afontain:

{{InfoBoxStart | name = Light Armor | image = Light-armor-lasgun-0.52.png | caption = Fancy armor. Weapon sold separately.}}
{{InfoRow | caption = Cost | value = 200 }}
{{InfoRow | caption = Unlock | value = 0 }}
{{InfoBoxSection | name = % of base damage }}
{{InfoRow | caption = Head | value = 80% }}
{{InfoRow | caption = Torso Back | value = 50% }}
{{InfoRow | caption = Torso Front | value = 35% }}
{{InfoRow | caption = Legs | value = 25% }}
{{InfoRow | caption = Non-Locational | value = 50% }}
{{InfoBoxEnd}}

This will be your first armor, grab it as soon as you can on the battlefield. Before even weapons!
[[Category:Humans]]

Medium Armour

2021-07-29T12:39:39Z

Afontain:

{{InfoBoxStart | name = Medium Armour | image = Armour medium.png | caption = The mobile killing armor.}}
{{InfoRow | caption = Cost | value = 300 }}
{{InfoRow | caption = Unlock | value = 3 }}
{{InfoBoxSection | name = % of base damage }}
{{InfoRow | caption = Head | value = 60% }}
{{InfoRow | caption = Torso Back | value = 35% }}
{{InfoRow | caption = Torso Front | value = 30% }}
{{InfoRow | caption = Legs | value = 20% }}
{{InfoRow | caption = Non-Locational | value = 30% }}
{{InfoBoxEnd}}

[[Category:Humans]]

Medium Armour

2021-07-29T12:37:35Z

Afontain:

Light Armour

2021-07-29T12:34:57Z

Afontain:

{{InfoBoxStart | name = Light Armor | image = Light-armor-lasgun-0.52.png | caption = Fancy armor. Weapon sold separately.}}
{{InfoRow | caption = Cost | value = 200 }}
{{InfoRow | caption = Unlock | value = 5 }}
{{InfoBoxSection | name = % of base damage }}
{{InfoRow | caption = Head | value = 80% }}
{{InfoRow | caption = Torso Back | value = 50% }}
{{InfoRow | caption = Torso Front | value = 35% }}
{{InfoRow | caption = Legs | value = 25% }}
{{InfoRow | caption = Non-Locational | value = 50% }}
{{InfoBoxEnd}}

This will be your first armor, grab it as soon as you can on the battlefield. Before even weapons!
[[Category:Humans]]

Light Armour

2021-07-29T12:34:38Z

Afontain:

{{InfoBoxStart | name = Light Armor | image = Light-armor-lasgun-0.52.png | caption = Fancy armor. Weapon sold separately.}}
{{InfoRow | caption = Cost | value = 400 }}
{{InfoRow | caption = Unlock | value = 5 }}
{{InfoBoxSection | name = % of base damage }}
{{InfoRow | caption = Head | value = 80% }}
{{InfoRow | caption = Torso Back | value = 50% }}
{{InfoRow | caption = Torso Front | value = 35% }}
{{InfoRow | caption = Legs | value = 25% }}
{{InfoRow | caption = Non-Locational | value = 50% }}
{{InfoBoxEnd}}

This will be your first armor, grab it as soon as you can on the battlefield. Before even weapons!
[[Category:Humans]]

File:Light-armor-lasgun-0.52.png

2021-07-29T12:29:00Z

Afontain: An human with a light armor and the new lasgun

== Summary ==
An human with a light armor and the new lasgun
== Licencing ==
{{licenses/cc-by-nc-sa-3.0}}