Lua AI Legacy Methods Howto - Revision history

Celtic Minstrel: Use syntax highlighting

2022-11-11T03:48:06Z

Use syntax highlighting

Celtic Minstrel: /* Lua AI Setup */ Use syntax highlighting

2022-11-11T03:43:29Z

‎Lua AI Setup: Use syntax highlighting

Mattsc: Add 'see also' link

2016-02-25T14:17:45Z

Add 'see also' link

Mattsc: Some changes to introduction

2016-02-23T19:57:48Z

Some changes to introduction

Mattsc: /* A Few More Useful Tidbits */ update a link

2016-02-23T19:47:12Z

‎A Few More Useful Tidbits: update a link

Mattsc: /* Adding / Deleting Stages and Candidate Actions */ Remove a section with content that is now available elsewhere (and not specific to Lua AI)

2016-02-23T19:45:25Z

‎Adding / Deleting Stages and Candidate Actions: Remove a section with content that is now available elsewhere (and not specific to Lua AI)

Mattsc: /* Using the Lua Stage */ update a link

2016-02-23T19:42:24Z

‎Using the Lua Stage: update a link

Mattsc: /* Behavior (Sticky) Candidate Actions */ remove a link which does not exist any more

2016-02-23T19:39:33Z

‎Behavior (Sticky) Candidate Actions: remove a link which does not exist any more

Mattsc: Remove a link to obsolete page

2016-02-23T17:27:01Z

Remove a link to obsolete page

Mattsc: Update internal links

2016-02-23T17:22:57Z

Update internal links

@@ Line 162: / Line 162: @@
 We circumvent these problems by using two little tricks.  First, we define that ''ai'' variable as global, meaning it needs to be defined first in the preload event, and it needs to be defined as 'ai = ...' rather than 'local ai = ...' in the engine, as described above.  Second, we let the AI play through its first turn, and then change the controller to ''human'' for the second turn.  This can be done either manually in debug mode using ':droid 1', or automatically by including the following event in the scenario:
      [event]
          name=side 1 turn 1 end
@@ Line 170: / Line 171: @@
          [/modify_side]
      [/event]
 If this event is used, it does not matter whether Side 2 is human or AI controlled, but setting it up as AI controlled means that we are immediately placed at the beginning of Turn 2 in control of Side 1, ready to test our AI code.
@@ Line 183: / Line 185: @@
 Even easier is placing this in a macro providing a right-click menu option:
- #define LUA_RELOAD_MENU
+<syntaxhighlight lang=wml>
      [event]
          name=start
@@ Line 198: / Line 201: @@
          [/set_menu_item]
      [/event]
- #enddef
+#enddef
 Once we place {LUA_RELOAD_MENU} in the [[ScenarioWML|[scenario]]] tag, all we need to do is choose this option from the right-click menu every time we change code in the file and test at will.
@@ Line 208: / Line 212: @@
 * Macro {LUA_AI_PRELOAD} as defined above, placed inside the [[ScenarioWML|[scenario]]] tag
 * An empty Lua engine definition, and the stages and candidate actions, placed inside the [[SideWML|[side]]] tag as follows:
      [ai]
          version=10710
@@ Line 245: / Line 250: @@
          [/stage]
      [ai]
 The stage and candidate action definition is, in principle, optional at this point, however, ''some'' stage doing ''something'' on Turn 1 is required, otherwise the ''ai'' variable is never defined (it only gets defined when it is needed).
@@ Line 251: / Line 257: @@
 * Macro {LUA_RELOAD_MENU} as defined above, placed inside the [[ScenarioWML|[scenario]]] tag
 * Finally, we want a file '~add-ons/LuaAI_tests/lua_manual.lua' with the following content:
- local my_ai = {}
+<syntaxhighlight lang=lua>
- function my_ai:go_south_evaluation()
+function my_ai:go_south_evaluation()
      local units = wesnoth.get_units
@@ Line 267: / Line 274: @@
      --print("Go south evaluation:", value)
      return value
- end
+end
- function my_ai:go_south_execution()
+function my_ai:go_south_execution()
      local units = wesnoth.get_units
@@ Line 279: / Line 286: @@
          ai.move_full(u, u.x, u.y+1)
      end
- end
+end
- -------------------------------------------------
+-------------------------------------------------
- wesnoth.clear_messages()
+wesnoth.clear_messages()
- local eval = my_ai:go_south_evaluation()
+local eval = my_ai:go_south_evaluation()
- if (eval > 0) then
+if (eval > 0) then
      my_ai:go_south_execution()
- end
+end
 The code below the dashed line can be any variation of AI function calls and can contain whatever debug message output is desired.
@@ Line 316: / Line 324: @@
 As an example, to apply the go-south code from above only to a unit with id 'Rark' on Side 1, we would use:
      [add_ai_behavior]
          side=1
@@ Line 326: / Line 335: @@
          execution="(...):go_south_execution('Rark')"
      [/add_ai_behavior]
 This declaration needs to be placed inside [[ActionWML]] ''after'' the unit has been created.  In the code, 'sticky' means that the candidate action is tied to the unit defined by [[StandardUnitFilter|[filter]]].  'loop_id' needs to be the id of the RCA AI stage. Usually that is ''main_loop''.  The evaluation score is hard-coded to 300,000 in order for the BCA to be executed before all other CAs.  'execution' calls ''my_ai:go_south_execution()'' in the same way as before, but now using parameter 'Rark'.  The execution function then needs to be:
- function my_ai:go_south_execution(id)
+<syntaxhighlight lang=lua>
      local unit = wesnoth.get_units { id = id }[1]
      ai.move_full(unit, unit.x, unit.y+1)
- end
+end
 If ''go_south_execution(id)'' is only to be done when Rark is wounded, an evaluation function similar to the previous version can be used.  Then, Rark would only go south if wounded, and partake in normal AI behavior otherwise, entirely equivalent to the previous example.
@@ Line 344: / Line 356: @@
 If the candidate action evaluation mechanism of the RCA AI stage is not needed, Lua AI moves can also be programmed in separate [[Wesnoth_AI_Framework#Lua_stage|Lua stages]], either in place of or in addition to the RCA AI stage:
      [stage]
          engine=lua
@@ Line 350: / Line 363: @@
          code=<< Lua stage code >>
      [/stage]
 The code can be defined directly here, or included from a file using [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]].  However, since the Lua engine needs to be defined in any case (in the same way as for the previous example), the AI moves can just as well be defined again in the [engine] tag in exactly the same way as before.  They can then be called from the Lua stages entirely analogous to what was done before:
      [stage]
          engine=lua
@@ Line 359: / Line 374: @@
          code=<< (...):do_moves() >>
      [/stage]
 where we assume that a ''my_ai:do_moves()'' function is defined in the engine.  In that case, the only difference is that the evaluation functions are now not separated from the execution functions on the stage/candidate action level, but that both are taken care of by the ''do_moves()'' function.

@@ Line 16: / Line 16: @@
 Unlike Formula AI and the default ''cpp'' AI, Lua AI requires an engine to be defined (this is obsolete).  Specifically, it does not work in [modify_side].  Here is an example of such an [ai] tag:
-<div style="height: 250px; overflow:auto">
+<syntaxhighlight lang=wml>
           [ai]
               version=10710
@@ Line 55: / Line 55: @@
               [/stage]
           [/ai]
-</div>
+</syntaxhighlight>
 Note that a lot of this is simply setting up the default ''main_loop'' stage and candidate actions.  The important non-default lines are:
@@ Line 66: / Line 66: @@
 The remaining custom lines are setting up the custom candidate actions at the end of the code, which call the ''move_unittype_eval()'' and ''move_unittype_exec()'' functions.  These are defined in the ''luaai-demo_engine.lua'' file that is included in the [engine] tag:
-<div style="height: 250px; overflow:auto">
+<syntaxhighlight lang=lua>
   return {
       init = function(ai)
@@ Line 123: / Line 123: @@
       end
+  }
-</div>
+</syntaxhighlight>
 These functions set up and return a Lua table called ''luaai_demo'' which contains two functions ''move_unittype_eval()'' and ''move_unittype_exec()''.  These are the evaluation and execution functions that are called by the custom AI candidate actions.

← Older revision		Revision as of 14:17, 25 February 2016
Line 369:		Line 369:
	shows all the default Lua AI functions -- assuming that the ''ai'' variable has been initialized.		shows all the default Lua AI functions -- assuming that the ''ai'' variable has been initialized.

		+
		+	'''See also:''' [[Wesnoth_AI]]
	[[Category:AI]]		[[Category:AI]]

@@ Line 2: / Line 2: @@
 |'''Warning'''
 |-
-|This page describes some of the old methods available for setting up Lua AI functionality.  They are still working and described here because quite a bit of existing code still uses them.  It is, however, generally not recommended to use these methods for new code any more.  Use those described at [[Creating_Custom_AIs]] instead.
+|This page describes some of the old methods available for setting up Lua AI functionality.  They are still working and described here because quite a bit of existing code still uses them.  However, [[Creating_Custom_AIs|a new method]] is now available for this and should be used instead for new AI development.
 Also note that this page is not being updated any more.
 |}
-This page is meant as a practical guide how to set up and test Lua AI functionality in a scenario.  It does not give a complete description of Lua or Lua AI.  See [[LuaAI]] or [[LuaWML]] for that.  Make sure you have read [[General RCA AI Howto]] as a basic understanding of the purpose of AI engines, stages and candidate actions is assumed here.
+==Lua AI Setup==
-Also note that we do not explain all the different ways of setting things up here.  Instead, we focus on one specific method that works reasonably well.  Using variations thereof will hopefully be straightforward once the principles are understood.
+This page is meant as a practical guide for setting up and testing Lua AI functionality in a scenario.  It does not give a complete description of Lua or Lua AI.  See [[LuaAI]] or [[LuaWML]] for that.  Also note that we do not explain all the different ways of setting things up here.  Instead, we focus on one specific method that works reasonably well.  Using variations thereof will hopefully be straightforward once the principles are understood.
 Setting up a Lua AI requires the definition of a Lua AI engine in the [side] tag and one or more stages executing the individual AI actions.  We restrict ourselves here to the example of using the default ''main_loop'' stage with its candidate actions.

@@ Line 366: / Line 366: @@
 == A Few More Useful Tidbits ==
-* Setting up aspects and goals/targets is described at [[LuaAI#Aspects]] and not repeated here
+* Setting up aspects and goals/targets is described at [[LuaAI]] and not repeated here
 * ''debug_utils'' from [http://forum.wesnoth.org/viewtopic.php?f=58&t=28320&start=45 Wesnoth Lua Pack] is a very powerful tool to analyze what is going on when something is not working as expected.  It can be used to display the content of essentially any Wesnoth Lua data structure.  As an example, the following command:
   debug_utils.dbms(ai, false, "variable", false)

← Older revision		Revision as of 19:45, 23 February 2016
Line 363:		Line 363:

	where we assume that a ''my_ai:do_moves()'' function is defined in the engine. In that case, the only difference is that the evaluation functions are now not separated from the execution functions on the stage/candidate action level, but that both are taken care of by the ''do_moves()'' function.		where we assume that a ''my_ai:do_moves()'' function is defined in the engine. In that case, the only difference is that the evaluation functions are now not separated from the execution functions on the stage/candidate action level, but that both are taken care of by the ''do_moves()'' function.
−
−	~~== Adding / Deleting Stages and Candidate Actions ==~~
−
−	While the Lua AI engine needs to be defined at the beginning of the scenario in the [[SideWML\|[side]]] tag, stages and candidate actions can be added and removed at any time in the scenario. A large number of macros are available in [http://www.wesnoth.org/macro-reference.html#file:ai.cfg core/macros/ai.cfg] for this purpose.
−
−	~~Here are two code examples of deleting candidate actions from the default RCA AI stage. The first is done right at the beginning during the side definition:~~
−
−	~~[side]~~
−	~~side=2~~
−	~~{ai/aliases/stable_singleplayer.cfg}~~
−	~~[ai]~~
−	~~{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}~~
−	~~{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}~~
−	~~[/ai]~~
−	~~[/side]~~
−
−	~~The second is done in an event:~~
−	~~[side]~~
−	~~side=2~~
−	~~{ai/aliases/stable_singleplayer.cfg}~~
−	~~[/side]~~
−	~~[event]~~
−	~~name=some_event~~
−	~~{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}~~
−	~~{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}~~
−	~~[/side]~~

	== A Few More Useful Tidbits ==		== A Few More Useful Tidbits ==

@@ Line 344: / Line 344: @@
 == Using the Lua Stage ==
-If the candidate action evaluation mechanism of the RCA AI stage is not needed, Lua AI moves can also be programmed in separate [[LuaAI#Stages|Lua stages]], either in place of or in addition to the RCA AI stage:
+If the candidate action evaluation mechanism of the RCA AI stage is not needed, Lua AI moves can also be programmed in separate [[Wesnoth_AI_Framework#Lua_stage|Lua stages]], either in place of or in addition to the RCA AI stage:
      [stage]

@@ Line 310: / Line 310: @@
 == Behavior (Sticky) Candidate Actions ==
-[[LuaAI#Behavior.28sticky.29_candidate_actions|Behavior (Sticky) Candidate Actions]] (BCAs) are entirely equivalent to "normal" CAs except that they are specifically tied to a unit.  As such, the BCA is removed when the unit dies.  This has two advantages:
+Behavior (Sticky) Candidate Actions (BCAs) are entirely equivalent to "normal" CAs except that they are specifically tied to a unit.  As such, the BCA is removed when the unit dies.  This has two advantages:
 # The BCA code does not need to include checks whether the unit exists
 # No computation time is taken up for evaluating the BCA after the unit dies (although that is likely a very small amount of time saved)

@@ Line 156: / Line 156: @@
 * The AI to be initialized, but the player having control of the side
 * A right-click menu option to run Lua engine code
-* Specific attention is needed if the [[Lua_AI_Howto#The_data_Variable|''data'' variable]] is to be used
+* Specific attention is needed if the [[#The_data_Variable|''data'' variable]] is to be used
 === Initializing the AI ===
@@ Line 298: / Line 298: @@
 ==== Setting up the ''data'' Variable ====
-Note that the [[Lua_AI_Howto#The_data_Variable|''data'' variable]] is not set up in this testing environment, because it gets added by the engine to the '''local''' variable ''my_ai'' that is not available outside the engine.  If ''data'' is needed, there are two ways of dealing with this:
+Note that the [[#The_data_Variable|''data'' variable]] is not set up in this testing environment, because it gets added by the engine to the '''local''' variable ''my_ai'' that is not available outside the engine.  If ''data'' is needed, there are two ways of dealing with this:
 # Make ''my_ai'' a global variable for testing.  This requires setting it up with 'my_ai = {}' in the preload event, and deleting the 'local' in front of ''my_ai'' in the engine definition as well as in the file '~add-ons/LuaAI_tests/lua_manual.lua' (or deleting it entirely from the latter).