-- Scripting standard function, to call each player phase start
function do_upgrade_effects(player)
  local upgrades, candidates
   = effects.player_bonus(player, "Upgrade_Unit");

  if upgrades <= 0 then
    return;
  end

  candidates = {};
  for u in player:units_iterate() do
    -- We have to be careful not to strand units at sea, for example by
    -- upgrading a frigate to an ironclad while it was carrying a unit.
    if u:can_upgrade(true) then
      table.insert(candidates, u)	-- Potential candidate :)
    end
  end

  while upgrades > 0 and #candidates > 0 do
    -- Upgrade one unit.  The unit is chosen at random from the list of
    -- available candidates.
    local candidate_to_upgrade = random(1, #candidates)
    local u = candidates[candidate_to_upgrade]
    local type_from = u.utype;
    local type_to = player:can_upgrade(type_from);

    u:transform(type_to, game.autoupgrade_veteran_loss);
    notify.event(player, u.tile, E.UNIT_UPGRADED,
                 _("%s was upgraded for free to %s."),
                 type_from:name_translation(), u:link_text());
    table.remove(candidates, candidate_to_upgrade)
    upgrades = upgrades - 1
  end
end

-- An alternative function: upgrade units for veteranship gained (not for any ruleset)
function do_veteran_upgrades(player)
  for u in player:units_iterate() do
    local ut, v = u.utype, u.veteran
    while ut.obsoleted_by and player:can_build_direct(ut)
          and v > 0 do
      ut = ut.obsoleted_by
      v = v - 1
    end
    if ut ~= u.utype then
      local ut0 = u.utype
      if u:transform(ut, u.veteran - v) then
        notify.event(player, u.tile, E.UNIT_UPGRADED,
                     _("%s has gained enough experience to upgrade to %s."),
                     ut0:name_translation(), u:link_text());
      end
    end
  end
end