Rollback possibility of wesnoth.get_units matching recall list units

Now it's renamed to wesnoth.units.find_on_map.

wesnoth.units.find implements the case of finding units on either the map or a recall list.

changelog.md

@@ -45,7 +45,7 @@
    * wesnoth.wml_matches_filter renamed to wml.matches_filter (the old name still works)
    * Moved to units module: wesnoth.create_unit, wesnoth.get_unit, wesnoth.get_units, wesnoth.get_recall_units
    * The wesnoth.units module now acts like a metatable for unit userdata.
-   * wesnoth.units.find (formerly wesnoth.get_units) now supports x="recall",y="recall"
+   * New wesnoth.units.find gets units on either the map or any side's recall list.
  ### WML engine
    * Support upkeep in StandardUnitFilter
    * [effect]apply_to=variation now supports heal_full

data/ai/lua/ai_helper.lua

@@ -1058,7 +1058,7 @@ end
 
 function ai_helper.get_live_units(filter)
     -- Note: the order of the filters and the [and] tags are important for speed reasons
-    return wesnoth.units.find { { "not", { status = "petrified" } }, { "and", filter } }
+    return wesnoth.units.find_on_map { { "not", { status = "petrified" } }, { "and", filter } }
 end
 
 function ai_helper.get_units_with_moves(filter, exclude_guardians)
@@ -1068,7 +1068,7 @@ function ai_helper.get_units_with_moves(filter, exclude_guardians)
     if exclude_guardians then
         exclude_status = exclude_status .. ',guardian'
     end
-    return wesnoth.units.find {
+    return wesnoth.units.find_on_map {
         { "and", { formula = "moves > 0" } },
         { "not", { status = exclude_status } },
         { "and", filter }
@@ -1077,7 +1077,7 @@ end
 
 function ai_helper.get_units_with_attacks(filter)
     -- Note: the order of the filters and the [and] tags are important for speed reasons
-    return wesnoth.units.find {
+    return wesnoth.units.find_on_map {
         { "and", { formula = "attacks_left > 0 and size(attacks) > 0" } },
         { "not", { status = "petrified" } },
         { "and", filter }
@@ -1109,7 +1109,7 @@ function ai_helper.get_visible_units(viewing_side, filter)
     end
 
     local units = {}
-    local all_units = wesnoth.units.find()
+    local all_units = wesnoth.units.find_on_map()
     for _,unit in ipairs(all_units) do
         if unit:matches(filter_plus_vision) then
             table.insert(units, unit)
@@ -1169,7 +1169,7 @@ function ai_helper.get_attackable_enemies(filter, side, cfg)
     end
 
     local enemies = {}
-    local all_units = wesnoth.units.find()
+    local all_units = wesnoth.units.find_on_map()
     for _,unit in ipairs(all_units) do
         if wesnoth.is_enemy(side, unit.side)
            and (not unit.status.petrified)
@@ -1221,7 +1221,7 @@ function ai_helper.get_closest_enemy(loc, side, cfg)
 
     local x, y
     if not loc then
-        local leader = wesnoth.units.find { side = side, canrecruit = 'yes' }[1]
+        local leader = wesnoth.units.find_on_map { side = side, canrecruit = 'yes' }[1]
         x, y = leader.x, leader.y
     else
         x, y = loc[1], loc[2]
@@ -1316,7 +1316,7 @@ function ai_helper.get_dst_src(units, cfg)
     --   all parameters for wesnoth.find_reach
 
     if (not units) then
-        units = wesnoth.units.find { side = wesnoth.current.side }
+        units = wesnoth.units.find_on_map { side = wesnoth.current.side }
     end
 
     return ai_helper.get_dst_src_units(units, cfg)
@@ -1328,7 +1328,7 @@ function ai_helper.get_enemy_dst_src(enemies, cfg)
     --   all parameters for wesnoth.find_reach
 
     if (not enemies) then
-        enemies = wesnoth.units.find {
+        enemies = wesnoth.units.find_on_map {
             { "filter_side", { { "enemy_of", { side = wesnoth.current.side} } } }
         }
     end
@@ -1558,7 +1558,7 @@ function ai_helper.find_path_with_shroud(unit, x, y, cfg)
     if wesnoth.sides[viewing_side] and wesnoth.sides[viewing_side].shroud then
         local extracted_units = {}
         if (not cfg) or (not cfg.ignore_units) then
-            local all_units = wesnoth.units.find()
+            local all_units = wesnoth.units.find_on_map()
             for _,u in ipairs(all_units) do
                 if (u.side ~= viewing_side)
                     and (not ai_helper.is_visible_unit(viewing_side, u))
@@ -1777,7 +1777,7 @@ function ai_helper.get_attacks(units, cfg)
 
     -- Note: the remainder is optimized for speed, so we only get_units once,
     -- do not use WML filters, etc.
-    local all_units = wesnoth.units.find()
+    local all_units = wesnoth.units.find_on_map()
 
     local enemy_map, my_unit_map, other_unit_map = LS.create(), LS.create(), LS.create()
     for i,unit in ipairs(all_units) do
@@ -1990,7 +1990,7 @@ function ai_helper.get_attack_combos(units, enemy, cfg)
     -- TODO: generalize it so that it works not only for units with moves=0, but blocked units etc.
     local blocked_hexes = LS.create()
     if units[1] and (units[1].side == wesnoth.current.side) then
-        local all_units = wesnoth.units.find { side = wesnoth.current.side }
+        local all_units = wesnoth.units.find_on_map { side = wesnoth.current.side }
         for _,unit in ipairs(all_units) do
             if (unit.moves == 0) then
                 blocked_hexes:insert(unit.x, unit.y)

data/ai/lua/battle_calcs.lua

@@ -791,7 +791,7 @@ function battle_calcs.attack_rating(attacker, defender, dst, cfg, cache)
 
     -- We also need the leader (well, the location at least)
     -- because if there's no other difference, prefer location _between_ the leader and the defender
-    local leader = wesnoth.units.find { side = attacker.side, canrecruit = 'yes' }[1]
+    local leader = wesnoth.units.find_on_map { side = attacker.side, canrecruit = 'yes' }[1]
 
     ------ All the attacker contributions: ------
     -- Add up rating for the attacking unit
@@ -1159,7 +1159,7 @@ function battle_calcs.get_attack_map_unit(unit, cfg)
     -- MP left off the map (for enemy pathfinding)
     local units_MP = {}
     if (unit.side ~= wesnoth.current.side) then
-        local all_units = wesnoth.units.find { side = wesnoth.current.side }
+        local all_units = wesnoth.units.find_on_map { side = wesnoth.current.side }
         for _,unit in ipairs(all_units) do
             if (unit.moves > 0) then
                 table.insert(units_MP, unit)

data/ai/lua/ca_castle_switch.lua

@@ -35,7 +35,7 @@ function ca_castle_switch:evaluation(cfg, data)
         return 0
     end
 
-    local leader = wesnoth.units.find {
+    local leader = wesnoth.units.find_on_map {
             side = wesnoth.current.side,
             canrecruit = 'yes',
             formula = '(movement_left = total_movement) and (hitpoints = max_hitpoints)'
@@ -190,7 +190,7 @@ function ca_castle_switch:evaluation(cfg, data)
 end
 
 function ca_castle_switch:execution(cfg, data)
-    local leader = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+    local leader = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
 
     if AH.print_exec() then AH.print_ts('   Executing castle_switch CA') end
     if AH.show_messages() then wesnoth.wml_actions.message { speaker = leader.id, message = 'Switching castles' } end

data/ai/lua/generic_recruit_engine.lua

@@ -336,7 +336,7 @@ return {
 
         function do_recruit_eval(data)
             -- Check if leader is on keep
-            local leader = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+            local leader = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
 
             if (not leader) or (not wesnoth.get_terrain_info(wesnoth.get_terrain(leader.x, leader.y)).keep) then
                 return 0
@@ -566,7 +566,7 @@ return {
             end
 
             local recruit_type
-            local leader = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+            local leader = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
             repeat
                 recruit_data.recruit.best_hex, recruit_data.recruit.target_hex = ai_cas:find_best_recruit_hex(leader, recruit_data)
                 recruit_type = ai_cas:find_best_recruit(attack_type_count, unit_attack_type_count, recruit_effectiveness, recruit_vulnerability, attack_range_count, unit_attack_range_count, most_common_range_count)

data/ai/lua/patrol.lua

@@ -5,7 +5,7 @@ function patrol_gen(n, wp)
     -- n is the name of the unit, like Kiressh
     -- wp - a table of waypoint tables of form {x,y}
 
-    local unit = wesnoth.units.find({name=n})[1]
+    local unit = wesnoth.units.find_on_map({name=n})[1]
 
     local x, y = unit.x, unit.y
     local wpn = 1 --WayPoint Number - we have to remember which waypoint we are heading to

data/ai/micro_ais/cas/ca_assassin_move.lua

@@ -8,7 +8,7 @@ local function get_units_target(cfg)
         { "and", wml.get_child(cfg, "filter") }
     }
 
-    local target = wesnoth.units.find {
+    local target = wesnoth.units.find_on_map {
         { "filter_side", { { "enemy_of", { side = wesnoth.current.side } } } },
         { "and", wml.get_child(cfg, "filter_second") }
     }[1]

data/ai/micro_ais/cas/ca_bottleneck_move.lua

@@ -16,8 +16,8 @@ local function bottleneck_is_my_territory(map, enemy_map)
     -- Get copy of leader to do pathfinding from each hex to the
     -- front-line hexes, both own (stored in @map) and enemy (@enemy_map) front-line hexes
     -- If there is no leader, use first unit found
-    local unit = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+    local unit = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
-    if (not unit) then unit = wesnoth.units.find { side = wesnoth.current.side }[1] end
+    if (not unit) then unit = wesnoth.units.find_on_map { side = wesnoth.current.side }[1] end
     local dummy_unit = unit:clone()
 
     local territory_map = LS.create()
@@ -269,7 +269,7 @@ function ca_bottleneck_move:evaluation(cfg, data)
 
     -- Healing map: positions next to healers
     -- Healers get moved with higher priority, so don't need to check their MP
-    local healers = wesnoth.units.find { side = wesnoth.current.side, ability = "healing" }
+    local healers = wesnoth.units.find_on_map { side = wesnoth.current.side, ability = "healing" }
     BD_healing_map = LS.create()
     for _,healer in ipairs(healers) do
         for xa,ya in H.adjacent_tiles(healer.x, healer.y) do
@@ -294,7 +294,7 @@ function ca_bottleneck_move:evaluation(cfg, data)
     --   1. the rating of the unit on the target hex (if there is one)
     --   2. the rating of the currently considered unit on its current hex
 
-    local all_units = wesnoth.units.find { side = wesnoth.current.side }
+    local all_units = wesnoth.units.find_on_map { side = wesnoth.current.side }
     local current_rating_map = LS.create()
 
     for _,unit in ipairs(all_units) do
@@ -433,7 +433,7 @@ function ca_bottleneck_move:evaluation(cfg, data)
         BD_bottleneck_moves_done = true
     else
         -- If there's another unit in the best location, moving it out of the way becomes the best move
-        local unit_in_way = wesnoth.units.find { x = best_hex[1], y = best_hex[2],
+        local unit_in_way = wesnoth.units.find_on_map { x = best_hex[1], y = best_hex[2],
             { "not", { id = best_unit.id } }
         }[1]
         if (not AH.is_visible_unit(wesnoth.current.side, unit_in_way)) then

data/ai/micro_ais/cas/ca_fast_attack_utils.lua

@@ -134,7 +134,7 @@ function ca_fast_attack_utils.get_unit_copy(id, gamedata)
     -- already, otherwise store in there
 
     if (not gamedata.unit_copies[id]) then
-        local unit_proxy = wesnoth.units.find { id = id }[1]
+        local unit_proxy = wesnoth.units.find_on_map { id = id }[1]
         gamedata.unit_copies[id] = unit_proxy:clone()
     end
 

data/ai/micro_ais/cas/ca_fast_move.lua

@@ -23,7 +23,7 @@ function ca_fast_move:execution(cfg)
         if (not unit.status.guardian) then table.insert(units, unit) end
     end
 
-    local leader = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+    local leader = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
 
     local goals = {}
 

data/ai/micro_ais/cas/ca_forest_animals_move.lua

@@ -12,7 +12,7 @@ local function get_forest_animals(cfg)
     }
 
     local tusker_type = cfg.tusker_type or "no_unit_of_this_type"
-    local all_tuskers = wesnoth.units.find { side = wesnoth.current.side, type = tusker_type }
+    local all_tuskers = wesnoth.units.find_on_map { side = wesnoth.current.side, type = tusker_type }
     for _,tusker in ipairs(all_tuskers) do
         if (tusker.moves > 0) then table.insert(forest_animals, tusker) end
     end
@@ -20,7 +20,7 @@ local function get_forest_animals(cfg)
     -- Tusklets get moved by this CA if there are no tuskers left
     if not all_tuskers[1] then
         local tusklet_type = cfg.tusklet_type or "no_unit_of_this_type"
-        local tusklets = wesnoth.units.find { side = wesnoth.current.side, type = tusklet_type }
+        local tusklets = wesnoth.units.find_on_map { side = wesnoth.current.side, type = tusklet_type }
         for _,tusklet in ipairs(tusklets) do
             if (tusklet.moves > 0) then table.insert(forest_animals, tusklet) end
         end

data/ai/micro_ais/cas/ca_forest_animals_new_rabbit.lua

@@ -42,12 +42,12 @@ function ca_forest_animals_new_rabbit:execution(cfg)
     end
     table.sort(holes, function(a, b) return a.random > b.random end)
 
-    local rabbits = wesnoth.units.find { side = wesnoth.current.side, type = cfg.rabbit_type }
+    local rabbits = wesnoth.units.find_on_map { side = wesnoth.current.side, type = cfg.rabbit_type }
     number = number - #rabbits
     number = math.min(number, #holes)
 
     -- Now we simply take the first 'number' (randomized) holes
-    local tmp_unit = wesnoth.units.find { side = wesnoth.current.side }[1]
+    local tmp_unit = wesnoth.units.find_on_map { side = wesnoth.current.side }[1]
     for i = 1,number do
         local x, y = -1, -1
         if tmp_unit then

data/ai/micro_ais/cas/ca_forest_animals_tusker_attack.lua

@@ -44,7 +44,7 @@ function ca_forest_animals_tusker_attack:execution(cfg)
 
     -- The tusker moves as close to enemy as possible
     -- Closeness to tusklets is secondary criterion
-    local adj_tusklets = wesnoth.units.find {
+    local adj_tusklets = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         type = cfg.tusklet_type,
         { "filter_adjacent", { id = target.id } }

data/ai/micro_ais/cas/ca_forest_animals_tusklet_move.lua

@@ -10,7 +10,7 @@ local function get_tusklets(cfg)
 end
 
 local function get_tuskers(cfg)
-    local tuskers = wesnoth.units.find {
+    local tuskers = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         type = cfg.tusker_type
     }

data/ai/micro_ais/cas/ca_hang_out.lua

@@ -27,7 +27,7 @@ function ca_hang_out:evaluation(cfg, data)
         MAISD.insert_mai_self_data(data, cfg.ai_id, { mobilize_units = true })
 
         -- Need to unmark all units also (all units, with and without moves)
-        local units = wesnoth.units.find { side = wesnoth.current.side, { "and", wml.get_child(cfg, "filter") } }
+        local units = wesnoth.units.find_on_map { side = wesnoth.current.side, { "and", wml.get_child(cfg, "filter") } }
         for _,unit in ipairs(units) do
             MAIUV.delete_mai_unit_variables(unit, cfg.ai_id)
         end

data/ai/micro_ais/cas/ca_healer_move.lua

@@ -11,7 +11,7 @@ function ca_healer_move:evaluation(cfg, data)
     -- find an appropriate hex to back up other units
     local score = data.HS_healer_move_score or 105000
 
-    local all_healers = wesnoth.units.find {
+    local all_healers = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         ability = "healing",
         { "and", wml.get_child(cfg, "filter") }
@@ -27,7 +27,7 @@ function ca_healer_move:evaluation(cfg, data)
     end
     if (not healers[1]) then return 0 end
 
-    local all_healees = wesnoth.units.find {
+    local all_healees = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         { "and", wml.get_child(cfg, "filter_second") }
     }

data/ai/micro_ais/cas/ca_herding_attack_close_enemy.lua

@@ -2,7 +2,7 @@ local AH = wesnoth.require "ai/lua/ai_helper.lua"
 local M = wesnoth.map
 
 local function get_sheep(cfg)
-    local sheep = wesnoth.units.find {
+    local sheep = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         { "and", wml.get_child(cfg, "filter_second") }
     }

data/ai/micro_ais/cas/ca_herding_herd_sheep.lua

@@ -12,7 +12,7 @@ local function get_dogs(cfg)
 end
 
 local function get_sheep_to_herd(cfg)
-    local all_sheep = wesnoth.units.find {
+    local all_sheep = wesnoth.units.find_on_map {
         side = wesnoth.current.side,
         { "and", wml.get_child(cfg, "filter_second") },
         { "not", { { "filter_adjacent", { side = wesnoth.current.side, { "and", wml.get_child(cfg, "filter") } } } } }

data/ai/micro_ais/cas/ca_herding_sheep_runs_dog.lua

@@ -23,7 +23,7 @@ function ca_herding_sheep_runs_dog:execution(cfg)
     local sheep = get_next_sheep(cfg)
 
     -- Get the first dog that the sheep is adjacent to
-    local dog = wesnoth.units.find { side = wesnoth.current.side, { "and", wml.get_child(cfg, "filter") },
+    local dog = wesnoth.units.find_on_map { side = wesnoth.current.side, { "and", wml.get_child(cfg, "filter") },
         { "filter_adjacent", { x = sheep.x, y = sheep.y } }
     }[1]
 

data/ai/micro_ais/cas/ca_messenger_f_next_waypoint.lua

@@ -10,7 +10,7 @@ return function(cfg)
     -- Returns nil for all arguments if there are no messengers on the map
 
     local filter = wml.get_child(cfg, "filter") or { id = cfg.id }
-    local messengers = wesnoth.units.find { side = wesnoth.current.side, { "and", filter } }
+    local messengers = wesnoth.units.find_on_map { side = wesnoth.current.side, { "and", filter } }
     if (not messengers[1]) then return end
 
     local waypoints = AH.get_multi_named_locs_xy('waypoint', cfg)

data/ai/micro_ais/cas/ca_protect_unit_move.lua

@@ -26,7 +26,7 @@ function ca_protect_unit_move:execution(cfg, data)
     -- as long as they can still move
     for _,unit in ipairs(protected_units) do unit:extract() end
 
-    local units = wesnoth.units.find { side = wesnoth.current.side }
+    local units = wesnoth.units.find_on_map { side = wesnoth.current.side }
     local enemy_units = AH.get_attackable_enemies()
 
     local attack_map = BC.get_attack_map(units).units  -- enemy attack map

data/ai/micro_ais/cas/ca_recruit_random.lua

@@ -10,7 +10,7 @@ function ca_recruit_random:evaluation(cfg)
     -- Random recruiting from all the units the side has
 
     -- Check if leader is on keep
-    local leader = wesnoth.units.find { side = wesnoth.current.side, canrecruit = 'yes' }[1]
+    local leader = wesnoth.units.find_on_map { side = wesnoth.current.side, canrecruit = 'yes' }[1]
     if (not leader) or (not wesnoth.get_terrain_info(wesnoth.get_terrain(leader.x, leader.y)).keep) then
         return 0
     end

data/ai/micro_ais/cas/ca_swarm_move.lua

@@ -4,7 +4,7 @@ local M = wesnoth.map
 local ca_swarm_move = {}
 
 function ca_swarm_move:evaluation(cfg)
-    local units = wesnoth.units.find { side = wesnoth.current.side }
+    local units = wesnoth.units.find_on_map { side = wesnoth.current.side }
     for _,unit in ipairs(units) do
         if (unit.moves > 0) then return cfg.ca_score end
     end
@@ -17,7 +17,7 @@ function ca_swarm_move:execution(cfg)
     local vision_distance = cfg.vision_distance or 12
 
     -- If no close enemies, swarm will move semi-randomly, staying close together, but away from enemies
-    local all_units = wesnoth.units.find { side = wesnoth.current.side }
+    local all_units = wesnoth.units.find_on_map { side = wesnoth.current.side }
     local units, units_no_moves = {}, {}
     for _,unit in ipairs(all_units) do
         if (unit.moves > 0) then

data/ai/micro_ais/cas/ca_wolves_multipacks_attack.lua

@@ -36,7 +36,7 @@ function ca_wolves_multipacks_attack:execution(cfg)
             local wolves, attacks = {}, {}
             for _,pack_wolf in ipairs(pack) do
                 -- Wolf might have moved in previous attack -> use id to identify it
-                local wolf = wesnoth.units.find { id = pack_wolf.id }[1]
+                local wolf = wesnoth.units.find_on_map { id = pack_wolf.id }[1]
                 if wolf and (wolf.attacks_left > 0) then table.insert(wolves, wolf) end
             end
 
@@ -154,7 +154,7 @@ function ca_wolves_multipacks_attack:execution(cfg)
             local wolves_moves, wolves_no_moves = {}, {}
             for _,pack_wolf in ipairs(pack) do
                 -- Wolf might have moved in previous attack -> use id to identify it
-                local wolf = wesnoth.units.find { id = pack_wolf.id }[1]
+                local wolf = wesnoth.units.find_on_map { id = pack_wolf.id }[1]
                 if wolf then
                     if (wolf.moves > 0) then
                         table.insert(wolves_moves, wolf)

data/ai/micro_ais/cas/ca_wolves_multipacks_functions.lua

@@ -21,7 +21,7 @@ function wolves_multipacks_functions.assign_packs(cfg)
 
     local pack_size = cfg.pack_size or 3
 
-    local wolves = wesnoth.units.find { side = wesnoth.current.side, type = cfg.type or "Wolf" }
+    local wolves = wesnoth.units.find_on_map { side = wesnoth.current.side, type = cfg.type or "Wolf" }
     local packs = {}
 
     -- Find wolves that already have a pack number assigned

data/ai/micro_ais/engines/urudin_engine.lua

@@ -6,7 +6,7 @@ return {
 
         -- This is taken almost literally from 'Ka'lian under Attack' in 'Legend of Wesmere'
         function urudin:retreat()
-            local urudin = wesnoth.units.find({ side = 3, id = "Urudin" })[1]
+            local urudin = wesnoth.units.find_on_map({ side = 3, id = "Urudin" })[1]
             if urudin and urudin.valid then
                 local max_hp, hp = urudin.max_hitpoints, urudin.hitpoints
                 local turn = wesnoth.current.turn

data/ai/micro_ais/micro_ai_helper.lua

@@ -111,7 +111,7 @@ function micro_ai_helper.delete_CAs(side, ca_id_core, CA_parms)
         wesnoth.delete_ai_component(side, "stage[main_loop].candidate_action[" .. ca_id .. "]")
 
         -- Also need to delete variable stored in all units of the side, so that later MAIs can use these units
-        local units = wesnoth.units.find { side = side }
+        local units = wesnoth.units.find_on_map { side = side }
         for _,unit in ipairs(units) do
             MAIUV.delete_mai_unit_variables(unit, CA_parms.ai_id)
         end

data/campaigns/Delfadors_Memoirs/utils/sides.cfg

@@ -535,7 +535,7 @@
     [lua]
         code=<<
             local helper = wesnoth.require "helper"
-            local units = wesnoth.units.find( { side = 1 } )
+            local units = wesnoth.units.find_on_map( { side = 1 } )
             for i = 1, #units do
                 -- pick an advancement randomly, and remove others so advance() doesn't show the dialog
                 if units[i].advances_to[1] ~= nil then

data/campaigns/Eastern_Invasion/ai/ca_ogres_flee.lua

@@ -14,14 +14,14 @@ end
 function ca_ogres_flee:execution()
     local units = AH.get_units_with_moves { side = wesnoth.current.side }
 
-    local units_noMP = wesnoth.units.find { side = wesnoth.current.side,
+    local units_noMP = wesnoth.units.find_on_map { side = wesnoth.current.side,
         formula = 'movement_left = 0'
     }
 
     local width, height = wesnoth.get_map_size()
 
     -- Need the enemy map and enemy attack map if avoid_enemies is set
-    local enemies = wesnoth.units.find {  { "filter_side", { {"enemy_of", {side = wesnoth.current.side} } } } }
+    local enemies = wesnoth.units.find_on_map {  { "filter_side", { {"enemy_of", {side = wesnoth.current.side} } } } }
     local enemy_attack_map = BC.get_attack_map(enemies)
 
     local max_rating, best_hex, best_unit = - math.huge

data/campaigns/Heir_To_The_Throne/scenarios/17_Scepter_of_Fire.cfg

@@ -715,7 +715,7 @@
             # wmllint: markcheck off
             code= <<
                 local ai_helper = wesnoth.require "ai/lua/ai_helper.lua"
-                local delf = wesnoth.units.find { id = 'Delfador' }[1]
+                local delf = wesnoth.units.find_on_map { id = 'Delfador' }[1]
                 local sceptre_loc= wesnoth.special_locations.sceptre
                 local path = wesnoth.find_path(delf, sceptre_loc[1], sceptre_loc[2], {ignore_units = true, viewing_side = 0}) -- # wmllint: noconvert
                 _ = wesnoth.textdomain 'wesnoth-httt'

data/campaigns/Legend_of_Wesmere/scenarios/chapter1/03_Kalian_under_Attack.cfg

@@ -193,7 +193,7 @@
                 local my_ai = { }
 
                 function my_ai:retreat()
-                    local urudin = wesnoth.units.find({id="Urudin"})[1]
+                    local urudin = wesnoth.units.find_on_map({id="Urudin"})[1]
                     if urudin and urudin.valid then
                         local mhp, hp = urudin.max_hitpoints, urudin.hitpoints
                         local turn = wesnoth.current.turn

data/campaigns/Northern_Rebirth/scenarios/05b_Compelled.cfg

@@ -94,7 +94,7 @@
 
         [lua]
             code = <<
-                local u = wesnoth.units.find({ id = 'Tallin' })[1]
+                local u = wesnoth.units.find_on_map({ id = 'Tallin' })[1]
                 if u.level <= 1 then
                     u:transform('Dark Adept')
                 elseif u.level == 2 then

data/campaigns/Northern_Rebirth/scenarios/09b_Judgment.cfg

@@ -61,7 +61,7 @@
 
         [lua]
             code = <<
-                local u = wesnoth.units.find({ id = 'Tallin' })[1]
+                local u = wesnoth.units.find_on_map({ id = 'Tallin' })[1]
                 if u.type == 'Dark Adept' then
                     u:transform('Sergeant')
                 elseif u.type == 'Dark Sorcerer' then

data/campaigns/Secrets_of_the_Ancients/utils/sota-utils.cfg

@@ -1036,7 +1036,7 @@
         name=prestart
         [lua]
             code=<<
-                for i, u in ipairs(wesnoth.units.find { type = 'SotA Vampire Bat, SotA Blood Bat, SotA Dread Bat', x = 'recall' }) do
+                for i, u in ipairs(wesnoth.units.find_on_map { type = 'SotA Vampire Bat, SotA Blood Bat, SotA Dread Bat', x = 'recall' }) do
                     if u.type == 'SotA Vampire Bat' then
                         u:transform('Vampire Bat')
                     elseif u.type == 'SotA Blood Bat' then

data/campaigns/Son_Of_The_Black_Eye/ai/ca_transport_S6.lua

@@ -13,7 +13,7 @@ local ca_transport = {}
 -- Also unload units onto best hexes adjacent to landing site
 
 function ca_transport:evaluation()
-    local units = wesnoth.units.find { side = wesnoth.current.side, formula = 'movement_left > 0' }
+    local units = wesnoth.units.find_on_map { side = wesnoth.current.side, formula = 'movement_left > 0' }
 
     for i,u in ipairs(units) do
         if u.variables.destination_x and u.variables.destination_y then
@@ -25,7 +25,7 @@ function ca_transport:evaluation()
 end
 
 function ca_transport:execution()
-    local units = wesnoth.units.find {}
+    local units = wesnoth.units.find_on_map {}
 
     -- Need all transport units plus maps of all units, all transport units and
     -- all other units (as those block hexes accessible to transport units)

data/campaigns/Two_Brothers/ai/ca_muff_toras_move.lua

@@ -5,7 +5,7 @@ local BC = wesnoth.require "ai/lua/battle_calcs.lua"
 local muff_toras_move = {}
 
 function muff_toras_move:evaluation()
-    local muff_toras = wesnoth.units.find { id = 'Muff Toras' }[1]
+    local muff_toras = wesnoth.units.find_on_map { id = 'Muff Toras' }[1]
 
     if muff_toras and (muff_toras.moves > 0) then
         return 15000
@@ -15,8 +15,8 @@ function muff_toras_move:evaluation()
 end
 
 function muff_toras_move:execution()
-    local muff_toras = wesnoth.units.find { id = 'Muff Toras' }[1]
+    local muff_toras = wesnoth.units.find_on_map { id = 'Muff Toras' }[1]
-    local units = wesnoth.units.find { side = 3, { 'not', { id = 'Muff Toras' } } }
+    local units = wesnoth.units.find_on_map { side = 3, { 'not', { id = 'Muff Toras' } } }
     local enemies = AH.get_attackable_enemies()
     local enemy_attack_map = BC.get_attack_map(enemies)
 

data/campaigns/Under_the_Burning_Suns/utils/garak-abilities.cfg

@@ -12,10 +12,10 @@
             code=<<
                 local _ = wesnoth.textdomain "wesnoth-utbs"
 
-                local teachers = wesnoth.units.find { ability = "teaching", side = wesnoth.current.side }
+                local teachers = wesnoth.units.find_on_map { ability = "teaching", side = wesnoth.current.side }
 
                 for i, teacher in ipairs(teachers) do
-                    local students = wesnoth.units.find { side = wesnoth.current.side, { "filter_adjacent", { id = teacher.id } } }
+                    local students = wesnoth.units.find_on_map { side = wesnoth.current.side, { "filter_adjacent", { id = teacher.id } } }
 
                     if #students > 0 then -- don't divide by zero
                         wesnoth.scroll_to_tile(teacher.x, teacher.y)

data/campaigns/Wings_of_Victory/lua/lua.lua

@@ -25,14 +25,14 @@ res.turns_over_advantage = function()
 			local r, g, b = 255, 255, 255
 			if     team.__cfg.color == 1 then r, g, b = 255,   0,   0
 			elseif team.__cfg.color == 2 then r, g, b =   0,   0, 255 end
-			if # wesnoth.units.find( { side = side } ) == 0 then
+			if # wesnoth.units.find_on_map( { side = side } ) == 0 then
 				side_comparison = side_comparison .. string.format( tostring( _ "<span strikethrough='true' foreground='#%02x%02x%02x'>Side %d</span>") .. "\n",
 				r, g, b, side)
 			else
 				local income = team.total_income * income_factor
 				local units = 0
 				-- Calc the total unit-score here
-				for i, unit in ipairs( wesnoth.units.find { side = side } ) do
+				for i, unit in ipairs( wesnoth.units.find_on_map { side = side } ) do
 					if not unit.__cfg.canrecruit then
 						wesnoth.fire("unit_worth", { id = unit.id })
 						units = units + wml.variables["unit_worth"]

data/campaigns/tutorial/scenarios/01_Tutorial_part_1.cfg

@@ -198,7 +198,7 @@
 
         [lua]
             code= <<
-                local unit = wesnoth.units.find({id = "student"})[1]
+                local unit = wesnoth.units.find_on_map({id = "student"})[1]
                 local hp_diff = unit.max_hitpoints - unit.hitpoints
 
                 if hp_diff > 7 then hp_diff = 8 end

data/lua/core.lua

@@ -480,7 +480,7 @@ if wesnoth.kernel_type() == "Game Lua Kernel" then
 	--! Fakes the move of a unit satisfying the given @a filter to position @a x, @a y.
 	--! @note Usable only during WML actions.
 	function wesnoth.interface.move_unit_fake(filter, to_x, to_y)
-		local moving_unit = wesnoth.units.find(filter)[1]
+		local moving_unit = wesnoth.units.find_on_map(filter)[1]
 		local from_x, from_y = moving_unit.x, moving_unit.y
 
 		wesnoth.interface.scroll_to_hex(from_x, from_y)
@@ -522,6 +522,15 @@ if wesnoth.kernel_type() == "Game Lua Kernel" then
 			end
 		end
 	end
+
+	-- gets map and recalllist units.
+	function wesnoth.units.find(filter)
+		local res = wesnoth.units.find_on_map(filter)
+		for i, u in ipairs(wesnoth.units.find_on_recall(filter)) do
+			table.insert(res, u)
+		end
+		return res
+	end
 end
 
 --[========[GUI2 Dialog Manipulations]========]
@@ -611,7 +620,7 @@ if wesnoth.kernel_type() == "Game Lua Kernel" then
 	wesnoth.select_unit = wesnoth.deprecate_api('wesnoth.select_unit', 'wesnoth.units.select', 1, nil, wesnoth.units.select)
 	wesnoth.create_unit = wesnoth.deprecate_api('wesnoth.create_unit', 'wesnoth.units.create', 1, nil, wesnoth.units.create)
 	wesnoth.get_unit = wesnoth.deprecate_api('wesnoth.get_unit', 'wesnoth.units.get', 1, nil, wesnoth.units.get)
-	wesnoth.get_units = wesnoth.deprecate_api('wesnoth.get_units', 'wesnoth.units.find', 1, nil, wesnoth.units.find)
+	wesnoth.get_units = wesnoth.deprecate_api('wesnoth.get_units', 'wesnoth.units.find_on_map', 1, nil, wesnoth.units.find_on_map)
 	wesnoth.get_recall_units = wesnoth.deprecate_api('wesnoth.get_units', 'wesnoth.units.find_on_recall', 1, nil, wesnoth.units.find_on_recall)
 end
 wesnoth.tovconfig = wesnoth.deprecate_api('wesnoth.tovconfig', 'wml.tovconfig', 1, nil, wml.tovconfig)

data/lua/wml-tags.lua

@@ -137,12 +137,12 @@ end
 
 function wml_actions.fire_event(cfg)
 	local u1 = wml.get_child(cfg, "primary_unit")
-	u1 = u1 and wesnoth.units.find(u1)[1]
+	u1 = u1 and wesnoth.units.find_on_map(u1)[1]
 	local x1, y1 = 0, 0
 	if u1 then x1, y1 = u1.x, u1.y end
 
 	local u2 = wml.get_child(cfg, "secondary_unit")
-	u2 = u2 and wesnoth.units.find(u2)[1]
+	u2 = u2 and wesnoth.units.find_on_map(u2)[1]
 	local x2, y2 = 0, 0
 	if u2 then x2, y2 = u2.x, u2.y end
 
@@ -169,7 +169,7 @@ end
 
 function wml_actions.allow_extra_recruit(cfg)
 	local recruits = cfg.extra_recruit or helper.wml_error("[allow_extra_recruit] missing required extra_recruit= attribute")
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		local v = unit.extra_recruit
 		for recruit in utils.split(recruits) do
 			table.insert(v, recruit)
@@ -201,7 +201,7 @@ end
 
 function wml_actions.disallow_extra_recruit(cfg)
 	local recruits = cfg.extra_recruit or helper.wml_error("[disallow_extra_recruit] missing required extra_recruit= attribute")
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		local v = unit.extra_recruit
 		for w in utils.split(recruits) do
 			for i, r in ipairs(v) do
@@ -234,7 +234,7 @@ function wml_actions.set_extra_recruit(cfg)
 		table.insert(v, w)
 	end
 
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		unit.extra_recruit = v
 	end
 end
@@ -248,7 +248,7 @@ function wml_actions.store_map_dimensions(cfg)
 end
 
 function wml_actions.unit_worth(cfg)
-	local u = wesnoth.units.find(cfg)[1] or
+	local u = wesnoth.units.find_on_map(cfg)[1] or
 		helper.wml_error "[unit_worth]'s filter didn't match any unit"
 	local ut = wesnoth.unit_types[u.type]
 	local hp = u.hitpoints / u.max_hitpoints
@@ -324,7 +324,7 @@ function wml_actions.scroll_to(cfg)
 end
 
 function wml_actions.scroll_to_unit(cfg)
-	local u = wesnoth.units.find(cfg)[1]
+	local u = wesnoth.units.find_on_map(cfg)[1]
 	if not u then return end
 	if not utils.optional_side_filter(cfg, "for_side", "for_side") then return end
 	wesnoth.scroll_to_tile(u.x, u.y, cfg.check_fogged, cfg.immediate)
@@ -343,7 +343,7 @@ function wml_actions.unlock_view(cfg)
 end
 
 function wml_actions.select_unit(cfg)
-	local u = wesnoth.units.find(cfg)[1]
+	local u = wesnoth.units.find_on_map(cfg)[1]
 	if not u then return end
 	wesnoth.interface.select_unit(u.x, u.y, cfg.highlight, cfg.fire_event)
 end
@@ -354,7 +354,7 @@ end
 
 function wml_actions.unit_overlay(cfg)
 	local img = cfg.image or helper.wml_error( "[unit_overlay] missing required image= attribute" )
-	for i,u in ipairs(wesnoth.units.find(cfg)) do
+	for i,u in ipairs(wesnoth.units.find_on_map(cfg)) do
 		local has_already = false
 		for i, w in ipairs(u.overlays) do
 			if w == img then has_already = true end
@@ -374,7 +374,7 @@ end
 
 function wml_actions.remove_unit_overlay(cfg)
 	local img = cfg.image or helper.wml_error( "[remove_unit_overlay] missing required image= attribute" )
-	for i,u in ipairs(wesnoth.units.find(cfg)) do
+	for i,u in ipairs(wesnoth.units.find_on_map(cfg)) do
 		local has_already = false
 		for i, w in ipairs(u.overlays) do
 			if w == img then has_already = true end
@@ -403,24 +403,18 @@ function wml_actions.store_unit(cfg)
 
 	--cache the needed units here, since the filter might reference the to-be-cleared variable(s)
 	local units = wesnoth.units.find(filter)
-	local recall_units = wesnoth.units.find{x = 'recall', wml.tag["and"](filter)}
 
 	local writer = utils.vwriter.init(cfg, "unit")
 
 	for i,u in ipairs(units) do
+		local ucfg = u.__cfg
+		if u.valid == 'recall' then
+			ucfg.x = 'recall'
+			ucfg.y = 'recall'
+		end
 		utils.vwriter.write(writer, u.__cfg)
 		if kill_units then u:erase() end
 	end
-
-	if (not filter.x or filter.x == "recall") and (not filter.y or filter.y == "recall") then
-		for i,u in ipairs(recall_units) do
-			local ucfg = u.__cfg
-			ucfg.x = "recall"
-			ucfg.y = "recall"
-			utils.vwriter.write(writer, ucfg)
-			if kill_units then u:erase() end
-		end
-	end
 end
 
 function wml_actions.sound(cfg)
@@ -459,7 +453,7 @@ function wml_actions.store_reachable_locations(cfg)
 
 	local reach = location_set.create()
 
-	for i,unit in ipairs(wesnoth.units.find(unit_filter)) do
+	for i,unit in ipairs(wesnoth.units.find_on_map(unit_filter)) do
 		local unit_reach
 		if moves == "max" then
 			local saved_moves = unit.moves
@@ -491,14 +485,14 @@ function wml_actions.store_reachable_locations(cfg)
 end
 
 function wml_actions.hide_unit(cfg)
-	for i,u in ipairs(wesnoth.units.find(cfg)) do
+	for i,u in ipairs(wesnoth.units.find_on_map(cfg)) do
 		u.hidden = true
 	end
 	wml_actions.redraw {}
 end
 
 function wml_actions.unhide_unit(cfg)
-	for i,u in ipairs(wesnoth.units.find(cfg)) do
+	for i,u in ipairs(wesnoth.units.find_on_map(cfg)) do
 		u.hidden = false
 	end
 	wml_actions.redraw {}
@@ -547,7 +541,7 @@ function wml_actions.floating_text(cfg)
 end
 
 function wml_actions.petrify(cfg)
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		unit.status.petrified = true
 		-- Extract unit and put it back to update animation (not needed for recall units)
 		unit:extract()
@@ -560,7 +554,7 @@ function wml_actions.petrify(cfg)
 end
 
 function wml_actions.unpetrify(cfg)
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		unit.status.petrified = false
 		-- Extract unit and put it back to update animation (not needed for recall units)
 		unit:extract()
@@ -575,7 +569,7 @@ end
 function wml_actions.transform_unit(cfg)
 	local transform_to = cfg.transform_to
 
-	for index, unit in ipairs(wesnoth.units.find(cfg)) do
+	for index, unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 
 		if transform_to then
 			unit:transform(transform_to)
@@ -618,7 +612,7 @@ function wml_actions.store_side(cfg)
 end
 
 function wml_actions.add_ai_behavior(cfg)
-	local unit = wesnoth.units.find(wml.get_child(cfg, "filter"))[1] or
+	local unit = wesnoth.units.find_on_map(wml.get_child(cfg, "filter"))[1] or
 		helper.wml_error("[add_ai_behavior]: no unit specified")
 
 	local side = cfg.side or
@@ -687,7 +681,7 @@ function wml_actions.store_villages( cfg )
 end
 
 function wml_actions.put_to_recall_list(cfg)
-	local units = wesnoth.units.find(cfg)
+	local units = wesnoth.units.find_on_map(cfg)
 
 	for i, unit in ipairs(units) do
 		if cfg.heal then
@@ -884,7 +878,7 @@ end
 wml_actions.teleport = function(cfg)
 	local context = wesnoth.current.event_context
 	local filter = wml.get_child(cfg, "filter") or { x = context.x1, y = context.y1 }
-	local unit = wesnoth.units.find(filter)[1]
+	local unit = wesnoth.units.find_on_map(filter)[1]
 	if not unit then
 		-- No error if no unit matches.
 		return
@@ -966,7 +960,7 @@ function wesnoth.wml_actions.cancel_action(cfg)
 end
 
 function wesnoth.wml_actions.store_unit_defense(cfg)
-	local unit = wesnoth.units.find(cfg)[1] or helper.wml_error "[store_unit_defense]'s filter didn't match any unit"
+	local unit = wesnoth.units.find_on_map(cfg)[1] or helper.wml_error "[store_unit_defense]'s filter didn't match any unit"
 	local terrain = cfg.terrain
 	local defense
 
@@ -1023,7 +1017,7 @@ end
 
 function wml_actions.remove_trait(cfg)
 	local obj_id = cfg.trait_id
-	for _,unit in ipairs(wesnoth.units.find(cfg)) do
+	for _,unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		unit:remove_modifications({id = obj_id}, "trait")
 	end
 end

data/lua/wml/animate_unit.lua

@@ -7,7 +7,7 @@ local function add_animation(anim, cfg)
 	local filter = wml.get_child(cfg, "filter")
 	local unit
 	if filter then
-		unit = wesnoth.units.find{
+		unit = wesnoth.units.find_on_map{
 			limit = 1,
 			T["and"](filter)
 		}[1]

data/lua/wml/find_path.lua

@@ -4,7 +4,7 @@ local utils = wesnoth.require "wml-utils"
 function wesnoth.wml_actions.find_path(cfg)
 	local filter_unit = wml.get_child(cfg, "traveler") or helper.wml_error("[find_path] missing required [traveler] tag")
 	-- only the first unit matching
-	local unit = wesnoth.units.find(filter_unit)[1] or helper.wml_error("[find_path]'s filter didn't match any unit")
+	local unit = wesnoth.units.find_on_map(filter_unit)[1] or helper.wml_error("[find_path]'s filter didn't match any unit")
 	local filter_location = wml.get_child(cfg, "destination") or helper.wml_error( "[find_path] missing required [destination] tag" )
 	-- support for $this_unit
 	local this_unit = utils.start_var_scope("this_unit")

data/lua/wml/harm_unit.lua

@@ -21,7 +21,7 @@ function wml_actions.harm_unit(cfg)
 
 	local this_unit = utils.start_var_scope("this_unit")
 
-	for index, unit_to_harm in ipairs(wesnoth.units.find(filter)) do
+	for index, unit_to_harm in ipairs(wesnoth.units.find_on_map(filter)) do
 		if unit_to_harm.valid then
 			-- block to support $this_unit
 			wml.variables["this_unit"] = nil -- clearing this_unit
@@ -36,7 +36,7 @@ function wml_actions.harm_unit(cfg)
 			local harmer_filter = wml.get_child(cfg, "filter_second")
 			local experience = cfg.experience
 			local resistance_multiplier = tonumber(cfg.resistance_multiplier) or 1
-			if harmer_filter then harmer = wesnoth.units.find(harmer_filter)[1] end
+			if harmer_filter then harmer = wesnoth.units.find_on_map(harmer_filter)[1] end
 			-- end of block to support $this_unit
 
 			if animate then

data/lua/wml/heal_unit.lua

@@ -3,7 +3,7 @@ local T = wml.tag
 function wesnoth.wml_actions.heal_unit(cfg)
 	local healers = wml.get_child(cfg, "filter_second")
 	if healers then
-		healers = wesnoth.units.find{
+		healers = wesnoth.units.find_on_map{
 			ability_type = "heals",
 			T["and"](healers)
 		}
@@ -13,9 +13,9 @@ function wesnoth.wml_actions.heal_unit(cfg)
 
 	local who = wml.get_child(cfg, "filter")
 	if who then
-		who = wesnoth.units.find(who)
+		who = wesnoth.units.find_on_map(who)
 	else
-		who = wesnoth.units.find{
+		who = wesnoth.units.find_on_map{
 			x = wesnoth.current.event_context.x1,
 			y = wesnoth.current.event_context.y1
 		}

data/lua/wml/kill.lua

@@ -8,7 +8,7 @@ function wesnoth.wml_actions.kill(cfg)
 	local secondary_unit = wml.get_child(cfg, "secondary_unit")
 	local killer_loc = {0, 0}
 	if secondary_unit then
-		secondary_unit = wesnoth.units.find(secondary_unit)[1]
+		secondary_unit = wesnoth.units.find_on_map(secondary_unit)[1]
 		if cfg.fire_event then
 			if secondary_unit then
 				killer_loc = { x = tonumber(secondary_unit.x) or 0, y = tonumber(secondary_unit.y) or 0 }
@@ -17,7 +17,7 @@ function wesnoth.wml_actions.kill(cfg)
 			end
 		end
 	end
-	local dead_men_walking = wesnoth.units.find(cfg)
+	local dead_men_walking = wesnoth.units.find_on_map(cfg)
 	for i,unit in ipairs(dead_men_walking) do
 		local death_loc = {x = tonumber(unit.x) or 0, y = tonumber(unit.y) or 0}
 		if not secondary_unit then killer_loc = death_loc end

data/lua/wml/message.lua

@@ -225,7 +225,7 @@ local function get_speaker(cfg)
 	elseif cfg.speaker ~= nil then
 		speaker = wesnoth.units.get(cfg.speaker)
 	else
-		speaker = wesnoth.units.find(cfg)[1]
+		speaker = wesnoth.units.find_on_map(cfg)[1]
 	end
 
 	return speaker

data/lua/wml/modify_unit.lua

@@ -83,18 +83,6 @@ local function is_simple(cfg)
 	return true
 end
 
--- gets map and recalllist units.
-local function get_all_units(filter)
-	local res = wesnoth.units.find(filter)
-	if (not filter.x or filter.x == "recall") and (not filter.y or filter.y == "recall") then
-		--append recall units to result.
-		for i, u in ipairs(wesnoth.units.find_on_recall(filter)) do
-			res[#res + 1] = u
-		end
-	end
-	return res
-end
-
 local function simple_modify_unit(cfg)
 	local filter = wml.get_child(cfg, "filter") or helper.wml_error "[modify_unit] missing required [filter] tag"
 	-- todo: investigate the following attrtibutes:
@@ -189,7 +177,7 @@ local function simple_modify_unit(cfg)
 	end
 
 	local this_unit = utils.start_var_scope("this_unit")
-	for i, u in ipairs(get_all_units(filter)) do
+	for i, u in ipairs(wesnoth.units.find(filter)) do
 		wml.variables["this_unit"] = u.__cfg
 		handle_unit(u)
 	end

data/lua/wml/move_unit.lua

@@ -59,7 +59,7 @@ function wesnoth.wml_actions.move_unit(cfg)
 	if check_passability == nil then check_passability = true end
 	cfg = wml.literal(cfg)
 	cfg.to_location, cfg.to_x, cfg.to_y, cfg.fire_event, cfg.clear_shroud = nil
-	local units = wesnoth.units.find(cfg)
+	local units = wesnoth.units.find_on_map(cfg)
 
 	for current_unit_index, current_unit in ipairs(units) do
 		if not fire_event or current_unit.valid then

data/lua/wml/object.lua

@@ -18,7 +18,7 @@ function wml_actions.object(cfg)
 
 	local filter = wml.get_child(cfg, "filter")
 	if filter then
-		unit = wesnoth.units.find(filter)[1]
+		unit = wesnoth.units.find_on_map(filter)[1]
 	else
 		unit = wesnoth.units.get(context.x1, context.y1)
 	end
@@ -81,7 +81,7 @@ end
 
 function wml_actions.remove_object(cfg)
 	local obj_id = cfg.object_id
-	for _,unit in ipairs(wesnoth.units.find(cfg)) do
+	for _,unit in ipairs(wesnoth.units.find_on_map(cfg)) do
 		unit:remove_modifications({id = obj_id})
 	end
 end

data/lua/wml/role.lua

@@ -53,7 +53,7 @@ function wesnoth.wml_actions.role(cfg)
 
 	if not reassign then
 		if search_map then
-			local unit = wesnoth.units.find{role=role}[1]
+			local unit = wesnoth.units.find_on_map{role=role}[1]
 			if unit then
 				return
 			end
@@ -76,7 +76,7 @@ function wesnoth.wml_actions.role(cfg)
 			if #types > 0 then
 				filter.type = types[i]
 			end
-			local unit = wesnoth.units.find(filter)[1]
+			local unit = wesnoth.units.find_on_map(filter)[1]
 			if unit then
 				unit.role = role
 				return

data/multiplayer/eras.lua

@@ -12,7 +12,7 @@ res.quick_4mp_leaders = function(args)
 	end
 
 	local trait_quick = args[1][2]
-	for i, unit in ipairs(wesnoth.units.find { canrecruit = true, T.filter_wml { max_moves = 4 } }) do
+	for i, unit in ipairs(wesnoth.units.find_on_map { canrecruit = true, T.filter_wml { max_moves = 4 } }) do
 		if not unit.variables.dont_make_me_quick then
 			unit:add_modification("trait", trait_quick )
 			unit.moves = unit.max_moves
@@ -58,14 +58,14 @@ res.turns_over_advantage = function()
 			elseif team.__cfg.color == 7 then r, g, b = 255, 165,   0
 			elseif team.__cfg.color == 8 then r, g, b = 255, 255, 255
 			elseif team.__cfg.color == 9 then r, g, b =   0, 128, 128 end
-			if # wesnoth.units.find( { side = side } ) == 0 then
+			if # wesnoth.units.find_on_map( { side = side } ) == 0 then
 				side_comparison = side_comparison .. string.format( tostring( _ "<span strikethrough='true' foreground='#%02x%02x%02x'>Side %d</span>") .. "\n",
 				r, g, b, side)
 			else
 				local income = team.total_income * income_factor
 				local units = 0
 				-- Calc the total unit-score here
-				for i, unit in ipairs( wesnoth.units.find { side = side } ) do
+				for i, unit in ipairs( wesnoth.units.find_on_map { side = side } ) do
 					if not unit.__cfg.canrecruit then
 						wesnoth.fire("unit_worth", { id = unit.id })
 						units = units + wml.variables["unit_worth"]

data/multiplayer/scenarios/2p_Dark_Forecast.lua

@@ -262,13 +262,13 @@ end
 -- convert all 'veteran' units from side 2 to the more aggressive side 1
 -- this must happen before the new units are created from spawns.
 on_event("new turn", function()
-	for i, unit in ipairs(wesnoth.units.find { side = 2 }) do
+	for i, unit in ipairs(wesnoth.units.find_on_map { side = 2 }) do
 		unit.side = 1
 	end
 end)
 
 on_event("prestart", function()
-	local leaders = wesnoth.units.find { side = "3,4", canrecruit= true}
+	local leaders = wesnoth.units.find_on_map { side = "3,4", canrecruit= true}
 	if #leaders < 2 then
 		create_timed_spaws(5, 11, 50, 5, 4, 21)
 	else

data/scenario-test.cfg

@@ -1194,7 +1194,7 @@ end)
 
 if result.button == -1 then
     local ev = wesnoth.current.event_context
-    wesnoth.units.find{x=ev.x1, y=ev.y1}[1]:transform(types[result.list_item])
+    wesnoth.units.find_on_map{x=ev.x1, y=ev.y1}[1]:transform(types[result.list_item])
     wesnoth.fire("redraw", {})
 end
             >>
@@ -1265,7 +1265,7 @@ end
                 function wml_actions.my_lua_action(t)
                     wesnoth.fire("label", { text =
                         string.format("Lua says:\n%d units and %d gold on side %d",
-                            #wesnoth.units.find { side = t.on_side },
+                            #wesnoth.units.find_on_map { side = t.on_side },
                             wesnoth.sides[t.on_side].gold,
                             t.on_side),
                         x = t.x, y = t.y })
@@ -1307,7 +1307,7 @@ end
         first_time_only=no
         [lua]
             code=<<
-                for i,u in ipairs(wesnoth.units.find()) do
+                for i,u in ipairs(wesnoth.units.find_on_map()) do
                     if u.status.entangled then
                         u.moves = 0
                     end
@@ -1573,7 +1573,7 @@ My best advancement costs $next_cost gold and I’m $experience|% there."
         [lua]
             code = <<
                 wesnoth.set_village_owner(20, 1, 1)
-                local u = wesnoth.units.find({ lua_function = "has_teleport" })[1]
+                local u = wesnoth.units.find_on_map({ lua_function = "has_teleport" })[1]
                 local t, c = wesnoth.find_path(u, 23, 7)
                 for i,l in ipairs(t) do
                     wesnoth.fire("item",
@@ -3160,7 +3160,7 @@ For game purposes, the races group into factions; for example, orcs often cooper
             code=<<
                 wesnoth.units.to_recall { type = "Elvish Lady" }
                 local u = wesnoth.units.find_on_recall()[2]
-                local l = wesnoth.units.find { side = 1, canrecruit = true }[1]
+                local l = wesnoth.units.find_on_map { side = 1, canrecruit = true }[1]
                 local x, y = wesnoth.find_vacant_tile(l.x, l.y, u)
                 u.side = 3
                 u:to_map(x, y)

src/scripting/game_lua_kernel.cpp

@@ -559,12 +559,6 @@ int game_lua_kernel::intf_get_displayed_unit(lua_State *L)
 int game_lua_kernel::intf_get_units(lua_State *L)
 {
 	vconfig filter = luaW_checkvconfig(L, 1, true);
-	
-	if(filter["x"] == "recall" || filter["y"] == "recall") {
-		lua_pop(L, 1);
-		return intf_get_recall_units(L);
-	}
-
 	unit_filter filt(filter);
 	std::vector<const unit*> units;
 
@@ -4339,7 +4333,7 @@ game_lua_kernel::game_lua_kernel(game_state & gs, play_controller & pc, reports
 		{"remove_modifications", &intf_remove_modifications},
 		// Static functions
 		{"create", &intf_create_unit},
-		{"find", &dispatch<&game_lua_kernel::intf_get_units>},
+		{"find_on_map", &dispatch<&game_lua_kernel::intf_get_units>},
 		{"find_on_recall", &dispatch<&game_lua_kernel::intf_get_recall_units>},
 		{"get", &dispatch<&game_lua_kernel::intf_get_unit>},
 		{ nullptr, nullptr }