Tales of Maj'Eyal - User contributions [en]

T4 Modules Howto Guide/Talents

2013-10-21T07:42:56Z

Grazz: /* Talent Definitions */

=Talents: Your special skills=

==Talent Definitions==

By default, Talent definitions are stored in the /data/talents.lua file. This file can include other files through the use of the Load(file) method.

Talent definitions require talent type definitions first. These are defined in newTalentType{...} blocks.

<table class="wikitable">
<tr>
<th>Important TalentType Variables</th>
<th>Effect</th>
</tr>
<tr>
<td>name</td>
<td>Display name of this talent type. REQUIRED.</td>
</tr>
<tr>
<td>type</td>
<td>Identifier of this talent type. REQUIRED.</td>
</tr>
<tr>
<td>description</td>
<td>String description of this talent type.</td>
</tr>
<tr>
<td>points</td>
<td>Maximum amount of points in this talent type.</td>
</tr>
</table>

Note: If you are writing your own module you will need to add code to check how many points are in a talent as the engine's canLearnTalent function ignores the points definition when checking if a talent is learnable.

Talent definitions are defined in newTalent{...} blocks.

<table class="wikitable">
<tr>
<th>Important Talent Variables</th>
<th>Effect</th>
</tr>
<tr>
<td>name</td>
<td>Displayed Talent name. REQUIRED.</td>
</tr>
<tr>
<td>short_name</td>
<td>Talent identifier. name is used if unset.</td>
</tr>
<tr>
<td>points</td>
<td>Maximum amount of points that can be put into the talent.</td>
</tr>
<tr>
<td>require</td>
<td>Requirements table for adding points. See the requirements definition below.</td>
</tr>
<tr>
<td>mode</td>
<td>Talent mode. One of either: "passive" - always on, "sustained" - can be turned on or off and "activated" - can be used. Default is "activated".</td>
</tr>
<tr>
<td>info</td>
<td>String description of the talent. REQUIRED.</td>
</tr>
<tr>
<td>type</td>
<td>Talent group. REQUIRED.</td>
</tr>
<tr>
<td>cooldown</td>
<td>Amount of turns to wait before a talent can be used again.</td>
</tr>
<tr>
<td>range</td>
<td>Range of talent. May be a number or function, but use getTalentRange(t) below as a getter in that case.</td>
</tr>
</table>

Identifiers for the talents are created by uppercasing the short_name (or name if no short_name is defined), replacing spaces with underscores ('_') and appending T_ in the front. These can then be accessed statically through [ActorTalents.*].

In this way the talent "Wind Walk" can be accessed by [ActorTalents.T_WIND_WALK].

Some talent variables require functions to be defined. These are of the form function(self, t), where self is the invoking actor and t is the talent being invoked.

<table class="wikitable">
<tr>
<th>Important Talent Functions</th>
<th>Use</th>
</tr>
<tr>
<td>action</td>
<td>"activated" mode talents only. Function that gets used when talent is activated.</td>
</tr>
<tr>
<td>activate</td>
<td>"sustained" mode talents only. Function that gets used when talent gets turned on.</td>
</tr>
<tr>
<td>deactivate</td>
<td>"sustained" mode talents only. Function that gets used when talent gets turned off.</td>
</tr>
<tr>
<td>on_learn</td>
<td>Function that gets used when talent is learned.</td>
</tr>
<tr>
<td>on_unlearn</td>
<td>Function that gets used when talent is unlearned.</td>
</tr>
</table>

In order to add stat, level or other talent requirements, a requirement table is required. These are the recognised variables.

<table class="wikitable">
<tr>
<th>Requirement Definition</th>
<th>Use</th>
</tr>
<tr>
<td>stat</td>
<td>Actor must have these stats at these levels.</td>
</tr>
<tr>
<td>level</td>
<td>Actor must be at least this level.</td>
</tr>
<tr>
<td>talent</td>
<td>Prerequisite talents.</td>
</tr>
</table>

For instance if a talent requires another talent and stats you can use:

<pre>require = { stat = { str = 10, dex = 10 }, talent = { Talents.T_STONE_SKIN }, },</pre>

If a talent requires that another talent NOT be taken you can use

<pre>require = { talent = { { Talents.T_STONE_SKIN, false }, }, },</pre>

==Talent Targeting==

Many activatable talents require some user targeting input. This is done through a coroutine. This is an example of the standard targeting and dealing damage case:

<pre>local tg = {type="bolt", range=self:getTalentRange(t), talent=t}
local x, y = self:getTarget(tg)
if not x or not y then return nil end
self:project(tg, x, y, DamageType.FIRE, 10, nil)</pre>

In this case, tg contains the targeting and damage settings. Possible variables are:

<table class="wikitable">
<tr>
<th>Targeting Settings</th>
<th>Effect</th>
</tr>
<tr>
<td>type</td>
<td>Targeting type. See below.</td>
</tr>
<tr>
<td>range</td>
<td>Range limit. Usually always self:getTalentRange(t).</td>
</tr>
<tr>
<td>talent</td>
<td>The talent being used.</td>
</tr>
<tr>
<td>friendlyfire</td>
<td>(?) Defaults to true.</td>
</tr>
<tr>
<td>no_restrict</td>
<td>Makes no restrictions regarding targeting</td>
</tr>
<tr>
<td>stop_block</td>
<td>Denotes that the projection will be blocked by entities that block move (bolts have this true by default)</td>
</tr>
<tr>
<td>radius</td>
<td>"ball" and "cone" targeting modes use this.</td>
</tr>
<tr>
<td>cone_angle</td>
<td>"cone" targeting mode uses this. Defaults to 55.</td>
</tr>
<tr>
<td>msg</td>
<td>Message to display during targeting.</td>
</tr>
</table>

The possible targeting modes are:

<table class="wikitable">
<tr>
<th>type</th>
<th>Effect</th>
</tr>
<tr>
<td>hit</td>
<td>Simple single target.</td>
</tr>
<tr>
<td>bolt</td>
<td>Hits first thing in path.</td>
</tr>
<tr>
<td>beam</td>
<td>Hits everything in path.</td>
</tr>
<tr>
<td>ball</td>
<td>Hits everything in a ball around the target.</td>
</tr>
<tr>
<td>cone</td>
<td>Hits everything in a cone in the direction.</td>
</tr>
</table>

getTarget(tg) is a method that is overriden by an AI for NPCs, or by the game module class.

Note that the last parameter of the project() method is the particle system to use.

==ActorTalents Class==

By default, Actors inherit from the ActorTalents class, even in the example module. This class provides an interface for manipulating and accessing talents. These are some of the valuable methods.

<table class="wikitable">
<tr>
<th>Useful Talent Related ActorTalents class methods</th>
<th>Use</th>
</tr>
<tr>
<td>useTalent(t)</td>
<td>Forces the Actor to use the talent.</td>
</tr>
<tr>
<td>useTalents()</td>
<td>Shows the use talent dialog.</td>
</tr>
<tr>
<td>knowTalent(t)</td>
<td>Returns true if the talent is known.</td>
</tr>
<tr>
<td>knowTalentType(tt)</td>
<td>Returns true if the talent group is known.</td>
</tr>
<tr>
<td>learnTalent(t, force, nb)</td>
<td>Has an Actor learn a talent. force prevents a canLearnTalent(t) test. nb is the amount of points to put into the talent.</td>
</tr>
<tr>
<td>unlearnTalent(t)</td>
<td>Makes the Actor forget the talent.</td>
</tr>
<tr>
<td>learnTalentType(tt, v)</td>
<td>Has the Actor learns a Talent Type. (v is true or false?)</td>
</tr>
<tr>
<td>unlearnTalentType(tt)</td>
<td>Has the Actor forget a Talent Type.</td>
</tr>
<tr>
<td>canLearnTalent(t)</td>
<td>Returns true if the Actor meets the requirements for the talent.</td>
</tr>
<tr>
<td>getTalentLevel(t)</td>
<td>Gets the amount of points in talent. 0 if unlearned.</td>
</tr>
<tr>
<td>isTalentCoolingDown(t)</td>
<td>Returns true if the specified talent is in the process of cooldown.</td>
</tr>
<tr>
<td>getTalentRange(t)</td>
<td>Returns the talent range. Use this instead of checking the range variable, since this allows the range variable to be either a function or a number.</td>
</tr>
<tr>
<td>cooldownTalents()</td>
<td>Cools down all talents by 1. This needs to be in your act() method.</td>
</tr>
</table>

All of the above methods can also be redefined in your own class if their functionality needs to be expanded. In addition, the following may also be useful to redefine:

<table class="wikitable">
<tr>
<th>Method</th>
<th>Use</th>
</tr>
<tr>
<td>preUseTalent(t)</td>
<td>Called before an actor uses a talent. Not returning true stops the talent from invoking.</td>
</tr>
<tr>
<td>postUseTalent(t)</td>
<td>Called after an actor uses a talent. Not returning true stops stops cooldown or sustained state from happening.</td>
</tr>
<tr>
<td>getTalentFullDescription(t)</td>
<td>Used in Dialogs. Overload to add more information such as mana use.</td>
</tr>
</table>

Go back to [[T4 Modules Howto Guide]]

{{Module Guides}}

T4 Modules Howto Guide/NPCs

2013-10-19T16:44:20Z

Grazz: warning on setting rarity to 0

<h1 id="toc0">Actors: NPCs and Monsters</h1>

<h2 id="toc1">Important NPC Definitions</h2>

Note that these are also used in the copy table in a player descriptor. These expand on the properties available to all entities, see [[Entities]].

<table class="wikitable">
<tr>
<th>Variable</th>
<th>Effect</th>
</tr>
<tr>
<td>name</td>
<td>Displayed NPC name.</td>
</tr>
<tr>
<td>short_name</td>
<td>NPC identifier. name is used if unset</td>
</tr>
<tr>
<td>desc</td>
<td>Optional description of NPC.</td>
</tr>
<tr>
<td>type</td>
<td>NPC Type (No known hardcoded types)</td>
</tr>
<tr>
<td>subtype</td>
<td>Better categorization for NPC.</td>
</tr>
<tr>
<td>display</td>
<td>Character that the NPC is displayed as in text mode.</td>
</tr>
<tr>
<td>faction</td>
<td>Actor faction. Defaults to "enemies".</td>
</tr>
<tr>
<td>ai</td>
<td>Selects which ai to use for NPC.</td>
</tr>
<tr>
<td>ai_state</td>
<td>(?) Depends on AI class.</td>
</tr>
<tr>
<td>rarity</td>
<td>How common this NPC is to generate. Higher is rarer. If not set will not ever generate. Do not set to 0, this is bad.</td>
</tr>
<tr>
<td>level_range</td>
<td>Minimum and maximum levels for NPC. Read NPC Level Scaling below.</td>
</tr>
<tr>
<td>autolevel</td>
<td>Which leveling function to use to level up NPC. Read NPC Level Scaling below.</td>
</tr>
<tr>
<td>max_life</td>
<td>Max life at level 1.</td>
</tr>
<tr>
<td>energy.mod</td>
<td>Scales how much energy is gained per tick. Defaults to 1.</td>
</tr>
<tr>
<td>sight</td>
<td>Sight radius.</td>
</tr>
<tr>
<td>exp_mod</td>
<td>Scales how much exp is needed to reach a new level. Defaults to 1.</td>
</tr>
<tr>
<td>exp_worth</td>
<td>Indicator of Actor exp value. By default, exp for killing an Actor is its level times this value.</td>
</tr>
<tr>
<td>egos</td>
<td>See ego section in [[Entities]]</td>
</tr>
<tr>
<td>egos_chance</td>
<td>See ego section in [[Entities]]</td>
</tr>
</table>

These variables are not set in the definitions file, though they can be. They can be useful to access in code however.

<table class="wikitable">
<tr>
<th>Important runtime variables</th>
<th>Effect</th>
</tr>
<tr>
<td>energy.value</td>
<td>Current energy of this actor. Defaults to 0.</td>
</tr>
<tr>
<td>self.energy.used</td>
<td>Set to true if some energy was used this tick.</td>
</tr>
<tr>
<td>life</td>
<td>Current life. Defaults to max_life.</td>
</tr>
<tr>
<td>dead</td>
<td>true if entity is dead. Different from undead.</td>
</tr>
<tr>
<td>level</td>
<td>Current Actor level.</td>
</tr>
<tr>
<td>exp</td>
<td>Current experience.</td>
</tr>
<tr>
<td>max_level</td>
<td>Maximum level for the Actor.</td>
</tr>
</table>

The example module implements several other variables in its Actor class and Combat interface. These are not hardcoded, but can be used as a base or example for implementing your own module.

<table class="wikitable">
<tr>
<th>Variable</th>
<th>Effect</th>
</tr>
<tr>
<td>combat_armor</td>
<td>Removes this amount from damage taken.</td>
</tr>
<tr>
<td>combat.dam</td>
<td>This is added to strength to determine the damage done by attacks.</td>
</tr>
</table>

<h2 id="toc2">Actor class important methods</h2>

For more information, read the documentation.

<table class="wikitable">
<tr>
<th>Method</th>
<th>Purpose</th>
</tr>
<tr>
<td>act()</td>
<td>Code that gets executed every time the entity gets to act.</td>
</tr>
<tr>
<td>canSee(actor)</td>
<td>Test if the actor can see the target actor. This does not check LOS or such, only the actual ability to see it, such as influenced by stealth, invisibility or telepathy. Returns true or false and a number from 0 to 100 representing the 'chance' to be seen.</td>
</tr>
<tr>
<td>getTarget()</td>
<td>Gets the Actor target. Redefined by player and AI.</td>
</tr>
<tr>
<td>setTarget(target)</td>
<td>Sets the actor target. Redefined by player and AI.</td>
</tr>
<tr>
<td>move(x, y, force)</td>
<td style="text-align: left;">Do NOT manually set the actor's x and y values. Use this method instead. Set force to true to not test for the presence of other entities. Returns true if a move was attempted and energy should propably be used.</td>
</tr>
<tr>
<td>moveDir(dir)</td>
<td>Moves in a certain direction. Calls move() internally.</td>
</tr>
<tr>
<td>canMove(x, y, terrain_only)</td>
<td>Checks if the Actor can go there. if terrain_only is true it only checks terrain and ignores the presence of actors and other entities.</td>
</tr>
<tr>
<td>teleportRandom(x, y, dist, min_dist)</td>
<td>Teleports randomly to x,y. dist is the radius of the effect, min_dist is a minimum radius of the effect and defaults to 0. Set dist to 0 for precise teleport.</td>
</tr>
<tr>
<td>useEnergy(amount)</td>
<td>Amount of energy to subtract from the actor in energy based time systems. Often used in the act() method after taking an action that takes time.</td>
</tr>
<tr>
<td>reactionToward(target)</td>
<td>Uses factions to check for hostility. -100 is fully hostile, 0 is neutral and 100 is friendly.</td>
</tr>
<tr>
<td>addTemporaryValue(prop, v, noupdate)</td>
<td>Changes a property on the actor, but returns an id so the value change can be reversed with a call to removeTemporaryValue(). If noupdate is true the property is not actually changed.</td>
</tr>
<tr>
<td>removeTemporaryValue(prop, id, noupdate)</td>
<td>Reverses a previous call to addTemporaryValue(). Use its returned id to reverse its change.</td>
</tr>
<tr>
<td>onTemporaryValueChange(prop, sub, v)</td>
<td>Does nothing. Redefine to perform some action when temporary values are applied or removed.</td>
</tr>
<tr>
<td>attr(prop, v, fix)</td>
<td>Non-temporarily increases or decreases an actor property. Use this for compatibility with temporary values above. If fix is set the property is set to v, not increased or decreased. Commonly, attr(prop) alone is used to check for the existance of a property instead of modifying it.</td>
</tr>
<tr>
<td>isNear(x, y, radius)</td>
<td>Checks whether the actor is within a certain radius of the passed coordinate.</td>
</tr>
</table>

In addition, defining stats automatically creates a getStat() function. For example, defining the stat str creates a getStr() function for you.

<h2 id="toc3">NPC Egos</h2>

<h2 id="toc4">NPC Level Scaling</h2>
<p>Depending on the zone settings, the spawned creatures can actually level with the player. This requires a level_range variable to be properly set and a levelup() method in the Actor class.</p>

<p>The level_range variable defines the possible range the creature can be. The entity will always be leveled up to at least its minimum level in the level range. It will also never be leveled above that range either.</p>

<p>The leveling method should be defined in Actor.lua. In ToME this method adds to the life, stamina and mana of actors. Alternatively, you can create several, and use the autolevel variable to pick which to call.</p>

<p>All creatures are always generated at level 1, then leveled up to reach their required level. Keep this is mind when creating the NPC descriptor. Note also that you can create your own levelup() function in the NPC descriptor if a unique levelup method is needed.</p>

<p>See [[Dev-Zones]] for more info</p>

Go back to [[T4 Modules Howto Guide]]

{{Module Guides}}