SummerOfCodeProposal 2011 LuaAI JodyNorthup - Revision history

Egallager: link cleanup

2023-05-04T00:55:12Z

link cleanup

Egallager: fix heading levels

2023-05-04T00:54:39Z

fix heading levels

Esr: Hide historical instance of "SVN" from mediawiki search to avoid false positives.

2013-03-21T01:51:59Z

Hide historical instance of "SVN" from mediawiki search to avoid false positives.

Upthorn: /* If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our

2011-04-17T14:29:33Z

/* If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our

Upthorn: /* If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our

2011-04-17T14:13:26Z

Upthorn: /* Deliverables */

2011-04-16T18:22:44Z

‎Deliverables

Upthorn: /* Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then". */

2011-04-16T18:22:37Z

‎Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

Upthorn: /* If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our

2011-04-16T02:35:16Z

Upthorn: /* Proposed WML extension */

2011-04-16T02:27:23Z

‎Proposed WML extension

Upthorn: /* Proposed WML extension */

2011-04-16T02:23:33Z

‎Proposed WML extension

@@ Line 120: / Line 120: @@
 ====Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?====
-Yes: I selected [[http://wiki.wesnoth.org/SoC_Ideas_LuaAI_2011|the Lua AI improvement]] project from your ideas list. I would like to focus on ensuring that UMC authors can easily include custom Lua AI code in their modules.
+Yes: I selected [[SoC_Ideas_LuaAI_2011|the Lua AI improvement]] project from your ideas list. I would like to focus on ensuring that UMC authors can easily include custom Lua AI code in their modules.
 ====Why did you choose this project?====

@@ Line 1: / Line 1: @@
 {{SoC2011Student_2|upthorn|SoC_Ideas_LuaAI_2011}}
+==Description==
 ====Jody Northup - Improve and extend Lua AI scripting facilities====
 This is the [[SoC_Ideas_LuaAI_2011|Lua AI improvement]] idea.<br/>
@@ Line 7: / Line 6: @@
 I expect the first step to involve an in-depth analysis of the C++ AI functions and an inventory of the gaps in the currently-implemented Lua AI API, followed by tedious Lua API programming to expose each of those functions. I expect that the second step will involve communication with the development community to determine good WML specifications for the use of Lua AI code in UMC modules.
-=IRC=
+==IRC==
 Upthorn, Upth
-=SoC Application=
+==SoC Application==
 [http://socghop.appspot.com/gsoc/proposal/review/google/gsoc2011/upthorn/1 SoC Application]
-=Questionnaire=
+==Questionnaire==
 (Largely copied from [[SummerOfCodeProposal_JodyNorthup|my successful application last year]])
 ===Basics===
@@ Line 209: / Line 208: @@
 I have provided my phone number in the application at google.
-=Project Details=
+==Project Details==
-==Overview==
+===Overview===
 I will improve and extend wesnoth's support for custom Lua AI scripts in two major steps<br/>
 Step one involves use of the Lua API to create several Lua interface functions to invoke C++ functions from, and seems fairly straightforward.<br/>
 Step two involves the extension of WML and the Lua API in order to better facilitate creation and customization of AIs, and is significantly more complex.<br/>
 For step two, I propose a couple of extensions and modifications to WML
-===[Lua] and [AI] tag enhancement===
+====[Lua] and [AI] tag enhancement====
 I propose to add a "source" element to [Lua] and [AI] tags as an alternative to the "code" element. The source element will specify the relative path to a Lua file which contains the desired Lua code.<br/>
 Files loaded from the "source" element in these tags will be indexed globally so that multiple WML modules can reference the same Lua script file without causing the file to be loaded into memory multiple times.
-===[group] tag===
+====[group] tag====
 I propose to create a "[group]" tag for scenario authors to specify AI scripts per-group of units. This would be accompanied by a "[groups]" subtag in unitWML, which contains a unit's group memberships in priority order. Additionally a group could be associated with a standard unit filter in order to automatically apply itself to all new units created which match the filter.<br/>
 Additionally, the Lua API will be extended to allow Lua scripts to send messages to unit groups, so that groups can be dynamically created and commanded during the execution of a scenario. This will be accomplished by significant additions to the WML parsing engine to teach it about the new unit group concept, creation of an as-yet indeterminate number of Lua or Lua API functions yet to be named, and possibly a group-related extension to Standard Unit Filters.<br/>
 Proposed syntax for the [group] tag is provided below, in the [[#Proposed WML extension|proposed WML extension]] section.
-==Deliverables==
+===Deliverables===
-===Mandatory===
+====Mandatory====
 # Full exposure to Lua of C++ AI support functions. -- Due by July 15th
 #* C++ AI support functions exposed to Lua interface -- Due by July 8th
@@ Line 240: / Line 239: @@
 #** Update wiki documentation of GroupWML and Lua to be thorough and coherent -- Due by August 26th
-===Optional===
+====Optional====
 To be determined via discussion with mentors and UMC development community.
-==Proposed WML extensions==
+===Proposed WML extensions===
-===[group] tag===
+====[group] tag====
-====Basic syntax====
+=====Basic syntax=====
 My current thinking is that a group tag will look like this
      [group]
@@ Line 260: / Line 259: @@
 The id element is the only mandatory element of the group tag. The other tags specify certain automated behaviors that apply to the group. An explanation of each element follows:
-=====id=====
+======id======
 A group id will be some locally unique identifier for the group. This is the name that will be used to issue orders to members of the group, or to add or remove units from the group's membership.
-=====automatic=====
+======automatic======
 The element "automatic" is a boolean element that specifies whether the wesnoth game engine should track and update the group's membership according to a supplied [[StandardUnitFilter]].<br/>
 The default value is "no", and a value of "yes" requires that the group have a [[StandardUnitFilter]] associated.
-=====[filter]=====
+======[filter]======
 This child tag will specify a [[StandardUnitFilter]] to which the group membership should be applied. <br/>
 If automatic is yes, the [filter] tag is mandatory, and group membership will automatically be updated such that all units matching the filter are considered members, and no units not matching the filter are.<br/>
 If automatic is no, units matching the filter will be added to the [group] at the time of the group's formation, but any further additions to or removals from the group will require an explicit WML or Lua command.
-=====[ai]=====
+======[ai]======
 This optional child tag will specify a supplementary ai to control member units. Groups without an [ai] child tag will be controlled by the overall [side] ai.
-===[[UnitWML]] extension===
+====[[UnitWML]] extension====
 To facilitate the use of groups, I propose to extend Unit data to include a subtag [ai_groups]
-====Basic Structure====
+=====Basic Structure=====
 The basic structure of the [ai_groups] tag will be as follows
      [ai_groups]
@@ Line 295: / Line 294: @@
 If, instead, the command issued to ranged_units was to prefer attacking swordsmen over archers, the elven archer in question would obey both orders, walking along its circular patrol, and attacking swordsmen in its range, but not archers.
-===[group] modification actions===
+====[group] modification actions====
 In addition to the wml extensions specified above, I propose a set of actions to allow WML authors to maintain groups manually.
-====Basic syntax====
+=====Basic syntax=====
      [add_to_group]
        unit_id=some_unit
@@ Line 375: / Line 374: @@
 Additionally these actions shall all be callable from Lua.
-===[[StandardUnitFilter]] extension===
+====[[StandardUnitFilter]] extension====
 In order to address units by group membership, I propose to add a "group" attribute to allowable unit filters. A [filter] containing a group attribute will only return units that are members of the group whose id is specified in the attribute.

@@ Line 84: / Line 84: @@
 I am not very good at strategy games, so I have not even attempted multiplayer yet (except to the extent of debugging Persistence WML in multiplayer contexts.)
-====If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.====
+====If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our S&shy;&shy;V&shy;&shy;N (during the evaluation period or earlier) please state so.====
 * I did submit a patch to correct the VC9 project files, but then I realized it was a duplicate of one from three weeks earlier.
 * [https://gna.org/patch/index.php?1612 Patch 1612] -- implements [http://www.wesnoth.org/forum/viewtopic.php?f=15&t=15880 Sapient's proposed changes to allied healing].
 * [https://gna.org/patch/?1619 Patch 1619] -- provides prototype implementation of [[SoC Ideas Persistent Gameworld#WML_Syntax|Crab's proposed WML syntax]] for saving/loading persistence data.
-* I gained commit access to the BfW SVN during (or slightly before) the coding period for last year's Summer of Code. It appears that I still retain this access.
+* I gained commit access to the BfW S&shy;&shy;V&shy;&shy;N during (or slightly before) the coding period for last year's Summer of Code. It appears that I still retain this access.
 * [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49222 Revision 49222] -- corrects a long-standing bug which caused MSVC9 compiled Wesnoth to crash when parsing a [trait] that lacks a description
 * [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49223 Revision 49223] -- exposes suitable_keep() c++ AI helper function to the Lua AI library.
@@ Line 182: / Line 182: @@
 ====Are you familiar with any of the following tools or languages?====
-     * Subversion (used for all commits)
+     * Sub&shy;&shy;version (used for all commits)
 Yes, I have used it extensively for gens development, megamix development, my work on ScummVM in 2009, and my work on Wesnoth last summer.
      * C++ (language used for all the normal source code)

@@ Line 91: / Line 91: @@
 * [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49222 Revision 49222] -- corrects a long-standing bug which caused MSVC9 compiled Wesnoth to crash when parsing a [trait] that lacks a description
 * [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49223 Revision 49223] -- exposes suitable_keep() c++ AI helper function to the Lua AI library.
-* [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49223 Revision 49236] -- updates suitable_keep() Lua AI handler not to use obsolete code pattern shown in other Lua AI function handlers.
+* [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49236 Revision 49236] -- updates suitable_keep() Lua AI handler not to use obsolete code pattern shown in other Lua AI function handlers.
 ===3) Communication skills===

@@ Line 90: / Line 90: @@
 * I gained commit access to the BfW SVN during (or slightly before) the coding period for last year's Summer of Code. It appears that I still retain this access.
 * [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49222 Revision 49222] -- corrects a long-standing bug which caused MSVC9 compiled Wesnoth to crash when parsing a [trait] that lacks a description
-* [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49222 Revision 49223] -- exposes suitable_keep() c++ AI helper function to the Lua AI library.
+* [http://svn.gna.org/viewcvs/wesnoth?view=rev&revision=49223 Revision 49223] -- exposes suitable_keep() c++ AI helper function to the Lua AI library.
 ===3) Communication skills===

@@ Line 227: / Line 227: @@
 #* C++ AI support functions exposed to Lua interface -- Due by July 8th
 #* Wiki documentation of all additions to Lua interface -- Due by July 15th
-# Lua loadable non-redundantly into WML from external files -- Due by August 5th
+# Lua loadable non-redundantly into WML from external files -- Due by July 27th
-#* Basic functionality of "source" element in [Lua] tags and [AI] tags with engine="Lua" -- Due by July 25th
+#* Lua file-loading deduplication functionality -- Due by July 27th
-#** WML properly parses "source" element and passes file contents to Lua engine -- Due by July 22nd
+#** Script manager tracks files loaded by wesnoth.dofile and wesnoth.require -- Due by July 20th
-#** Source element syntax and usage is thoroughly documented on -- Due by July 25th
+#** Script manager compares new requests to files already loaded, and return reference to the loaded file -- Due by July 27th
 # [group] tag -- Due by August 26th
-#* Fully define [group] tag syntax specification-- Due by August 10th
+#* Fully define [group] tag syntax specification-- Due by August 2nd
-#* Implement grouping -- Due By August 22nd
+#* Implement grouping -- Due By August 26th
-#** WML engine extensions to parse [group] tags and assign one-time [[StandardUnitFilter]] groups to relevant units. -- Due By August 12th
+#** WML engine extensions to parse [group] tags and assign one-time [[StandardUnitFilter]] groups to relevant units. -- Due By August 7th
-#** Lua interface extensions to support AI issuing commands by group (including continually updated [[StandardUnitFilter]] groups) -- Due by August 17th
+#** Lua interface extensions to support AI issuing commands by group (including continually updated [[StandardUnitFilter]] groups) -- Due by August 14th
-#** Lua interface extensions to allow adding and removing of specific units and unit filters to and from specific groups -- Due by August 22nd
+#** Lua interface extensions to allow adding and removing of specific units and unit filters to and from specific groups -- Due by August 19th
 #** Update wiki documentation of GroupWML and Lua to be thorough and coherent -- Due by August 26th

@@ Line 137: / Line 137: @@
 *# Provide thorough documentation for newly exposed Lua functions (by July 15th)
 **Milestone: By July 15th (Midterm), Lua AI has documented access to all C++ AI functionality.
-*July 15 - July 25th: WML enhancement for easy including of Lua scripts
+*July 15 - July 27th:
-*# Extend Lua-context tags to include "source" elements as alternative to "code" elements - By July 22nd
+*# Implement Lua script manager to track files loaded by wesnoth.require and wesnoth.dofile (by July 20th)
-*# Ensure that documentation for "source" element on wiki is thorough and complete - By July 25th
+*# Ensure that each such external Lua file is loaded into memory only once, regardless of how many modules it is called from. (By July 27th)
-**Milestone: By July 25th, WML authors can easily include Lua code that is not embedded directly in the WML file
+**Milestone: By July 27th Lua scripts can be called in multiple modules with minimal additional overhead
-*July 25th-August 5th: Implement Lua script manager to ensure that each external Lua file is loaded into memory only once, regardless of how many modules it is called from.
+*July 27th - August 26th: Implement unit grouping concept for AIs
-*August 5th - August 26th: Implement unit grouping concept for AIs
+*# Fully determine [group] tag specifications (By August 2nd)
-*# Fully determine [group] tag specifications -- By August 10th
+*# Implement group tag (By August 19th)
-*# Implement group tag -- By August 22nd
+*## Extend WML engine to parse and process [group] (By August 7th)
-*## Extend WML engine to parse and process [group] -- By August 12th
+*## Extend Lua interface to support group-based commands (Due by August 14th)
-*## Extend Lua interface to support group-based commands -- Due by August 17th
+*## Extend Lua interface to allow creation, deletion, and customization of groups (by August 19th)
-*## Extend Lua interface to allow creation, deletion, and customization of groups -- Due by August 22nd
+*## Update wiki documentation of GroupWML and Lua to be thorough and coherent(by August 26th)
 **Milestone: By August 26th (Final deadline) Lua AI can be scripted by UMC devs with full functionality of C++ AI, can be easily included in WML modules, and can make use of unit-grouping for fine-grained control of AI behavior. Additionally, all of these features are thoroughly documented on the wiki.
@@ Line 155: / Line 154: @@
 *May 23 - June 13: Finish exposing C++ AI functions to Lua
 **Milestone: By June 13th, Lua AI has access to all C++ AI functionality.
-*June 13 - June 19th: WML enhancement for easy including of Lua scripts
+*June 13 - June 20th:
-*# Extend Lua-context tags to include "source" elements as alternative to "code" elements
+*# Implement Lua script manager to track files loaded by wesnoth.require and wesnoth.dofile
-*# Ensure that documentation for "source" element on wiki is thorough and complete
+*# Ensure that each such external Lua file is loaded into memory only once, regardless of how many modules it is called from.
-*June 19th - June 26th: Implement Lua script manager to ensure that each external Lua file is loaded into memory only once, regardless of how many modules it is called from.
+*June 20th - July 15th: Implement unit grouping concept for AIs
 *# Fully determine [group] tag specifications
 *# Implement group tag

← Older revision		Revision as of 02:23, 16 April 2011
Line 245:		Line 245:

	==Proposed WML extension==		==Proposed WML extension==
−	Specification in ~~progress~~	+	===[group] tag===
		+	====Basic syntax====
		+	My current thinking is that a group tag will look like this
		+	[group]
		+	id=some_group_identifier
		+	automatic=no
		+	[filter]
		+	{optional [[StandardUnitFilter]]}
		+	[/filter]
		+	[ai]
		+	{optional [[AiWML\|AI specification]]}
		+	[/ai]
		+	[/group]
		+
		+	The id element is the only mandatory element of the group tag. The other tags specify certain automated behaviors that apply to the group. An explanation of each element follows:
		+
		+	=====id=====
		+	A group id will be some locally unique identifier for the group. This is the name that will be used to issue orders to members of the group, or to add or remove units from the group's membership.
		+
		+	=====automatic=====
		+	The element "automatic" is a boolean element that specifies whether the wesnoth game engine should track and update the group's membership according to a supplied [[StandardUnitFilter]].<br/>
		+	The default value is "no", and a value of "yes" requires that the group have a [[StandardUnitFilter]] associated.
		+
		+	=====[filter]=====
		+	This child tag will specify a [[StandardUnitFilter]] to which the group membership should be applied. <br/>
		+	If automatic is yes, the [filter] tag is mandatory, and group membership will automatically be updated such that all units matching the filter are considered members, and no units not matching the filter are.<br/>
		+	If automatic is no, units matching the filter will be added to the [group] at the time of the group's formation, but any further additions to or removals from the group will require an explicit WML or Lua command.
		+
		+	=====[ai]=====
		+	This optional child tag will specify a supplementary ai to control member units. Groups without an [ai] child tag will be controlled by the overall [side] ai.
		+
		+	===[[UnitWML]] extension===
		+	To facilitate the use of groups, I propose to extend Unit data to include a subtag [ai_groups]
		+	====Basic Structure====
		+	The basic structure of the [ai_groups] tag will be as follows
		+	[ai_groups]
		+	1=some_group_identifier
		+	...
		+	n=yet_another_group_identifier
		+	[/ai_groups]
		+
		+	Each element shall be a number, associated with the id of an extant and valid [group] tag. The number shall be the priority of group membership, such that if two groups are issued conflicting orders, a unit with membership in both gruops will only follow commands issued to the group with the lowest priority number.<br/>
		+	For example, assume an elven archer unit is assigned to a "forest_patrol" group and a "ranged_units" group such that
		+	[ai_groups]
		+	1=forest_patrol
		+	2=ranged_units
		+	[/ai_groups]
		+	A command is issued to forest_patrol for all member units to move along a circular route within a particular patch of forest and a command is then issued to ranged_units to assault the enemy keep.
		+	The elven archer in question will ignore the command issued to ranged_units and continue to walk along its circular patrol.<br/>
		+	If, instead, the command issued to ranged_units was to prefer attacking swordsmen over archers, the elven archer in question would obey both orders, walking along its circular patrol, and attacking swordsmen in its range, but not archers.
		+
		+	===[group] modification actions===
		+	In addition to the wml extensions specified above, I propose a set of actions to allow WML authors to maintain groups manually.
		+	====Basic syntax====
		+	[add_to_group]
		+	unit_id=some_unit
		+	group_id=some_group
		+	priority=1
		+	[/add_to_group]
		+
		+	[add_to_group]
		+	[filter]
		+	[[StandardUnitFilter]]
		+	[/filter]
		+	group_id=some_group
		+	priority=1
		+	[/add_to_group]
		+
		+	[remove_from_group]
		+	unit_id=some_unit
		+	group_id=some_group
		+	[/remove_from_group]
		+
		+	[remove_from_group]
		+	[filter]
		+	[[StandardUnitFilter]]
		+	[/filter]
		+	group_id=some_group
		+	[/remove_from_group]
		+
		+	[clear_groups]
		+	unit_id=some_unit
		+	[/clear_groups]
		+
		+	[clear_groups]
		+	[filter]
		+	[[StandardUnitFilter]]
		+	[/filter]
		+	[/clear_groups]
		+
		+	[delete_group]
		+	group_id=some_group
		+	[/delete_group]
		+
		+	[set_group_ai]
		+	group_id=some_group
		+	[ai]
		+	[[AiWML\|AI Specification]]
		+	[/ai]
		+	[/set_group_ai]
		+
		+	[clear_group_ai]
		+	group_id=some_group
		+	[/clear_group_ai]
		+
		+	[add_to_group] adds a single unit (specified in unit_id), or all units matching a [filter] to a group (specified in group_id). If the group does not exist it will be created. The optional priority element specifies what priority level to mark the new group memberships, and defaults to 1. The new membership will take priority over existing memberships with equal or lesser priority value.<br/>
		+	For instance, taking the elven_archer from our previous example, if we run
		+	[add_to_group]
		+	unit_id=elven_archer
		+	group_id=test_group
		+	priority=2
		+	[/add_to_group]
		+	the elven_archer's resulting memberships will be
		+	[ai_groups]
		+	1=forest_patrol
		+	2=test_group
		+	3=ranged_units
		+	[/ai_groups]
		+
		+	[remove_from_group] removes a single unit (specified in unit_id), or all units matching a [filter] from a group (specified in group_id). If the group does not exist, nothing happens.
		+
		+	[clear_groups] removes a single unit (specified in unit_id), or all units matching a [filter] from all current groups.
		+	spec
		+	[delete_group] destroys a current group (specified in group_id) and removes all units from its membership. If the group does not exist, nothing happens.
		+
		+	[set_group_ai] changes the supplementary ai running in a current group (specified in group_id) to the one specified in the [ai] child tag. If the group does not exist, it will be created.
		+
		+	[clear_group_ai] removes the supplementary ai running in a current group (specified in group_id) and reverts all members to the overall [side] ai. If the group does not exist, nothing happens.
		+
		+	Additionally these actions shall all be callable from Lua.