To get a notion of what commands our plan module needs to support, let's lay out a control script first. The ship will start by facing down across the screen, move forward at a set speed, and start firing as it travels down. After a second, it will veer off to the left and stop firing. This function will be laid out in the marsh-enemies.lua module, so save dogfighter.lua and reopen that module to add the following code:

    function()
      at (0.3) spawn.turret(50, -20)
      at (0.5) spawn.defender(140, -10,
        function ()
          face(90)
          go(100)
          fire("MachineGun", 50, 0)
          after (1) turn(60, 0.75)
          release("MachineGun")
        end
      )
    end

So, this gives us at least six functions to support:

The dogfighter module uses the plan module to support these functions, so save marsh-enemies.lua and create the new module, plan.lua, in the top level of the project. This file will start off with a skeleton similar to that of schedule.lua, as shown in the following snippet, with which it has a great deal in common:

local function bind(path, actions)
end
return function(self, path)
end

The plan will have the same sort of glue function, which will attach a set of actions to the plan function in the same way:

local function bind(path, actions)
  setfenv(path, actions)
  path()
end

However, where schedules are intended to run for a fixed amount of time, a ship's orders need to be carried out as long as it's alive, which could be highly variable. But since we expect plans to run off of a timer that will repeat indefinitely, this makes them more uniform to cancel once the plan function is exhausted. We just wait for one more firing of the timer so that we can get the timer source to cancel it.

  path()
  local finalize = coroutine.yield()
  timer.cancel(finalize.source)
end

The code to start a new plan from the glue function and arguments will be almost identical to that of schedule.lua:

return function(self, path)
  local actions = {facing = self.rotation}
  local plan = coroutine.wrap(bind)
  plan(path, actions)
  return plan
end

The easiest actions to implement will actually be the fire control ones:

  local actions = {facing = self.rotation}
  function actions.fire(name, xAim, yAim)
  end
  function actions.release(name)
  end
  local plan = coroutine.wrap(bind)

We'll put a sanity check in just so that if a designer (or programmer) misspells a weapon name or otherwise tries to fire a non-existent weapon, it doesn't crash the ship's entire plan:

  function actions.fire(name, xAim, yAim)
    if self.Weapons[name] then
      self.Weapons[name]:start(self, xAim, yAim)
    end
  end

We'll take a similar approach with the release function, but as a convenience, it can be called without any name to stop all firing weapons:

  function actions.release(name)
    if name and self.Weapons[name] then
      self.Weapons[name]:stop()
    else
      for name, weapon in pairs(self.Weapons) do
        weapon:stop()
      end
    end
  end

The go function is one of the functions that I was referring to when I mentioned that some functions get simpler when the base ship images are pointed to the right. It also stores the scalar speed to facilitate turning functions:

  local actions = {facing = self.rotation}
  function actions.go(speed)
    local angle = math.rad(actions.facing)
    self:setLinearVelocity(speed * math.cos(angle), speed * math.sin(angle))
    self.Speed = speed
  end
  function actions.fire(name, xAim, yAim)

Finally, we get to use turn(). This is a slightly more complicated function because it keeps control of the ship until the turn is complete. For convenience, it expects durations in seconds, not milliseconds, as shown in the following code:

    self.Speed = speed
  end
  function actions.turn(angle, duration)
    duration = duration * 1000
  end
  function actions.fire(name, xAim, yAim)

It needs to know how much time has passed since the last time it was checked, so it starts by noting the time it started:

  function actions.turn(angle, duration)
    duration = duration * 1000
    local start = system.getTimer()
  end

The function will continue reducing the duration by the elapsed time whenever it gets notified of time passing, until the complete duration has passed:

    local start = system.getTimer()
    while duration > 0 do
      local elapsed = coroutine.yield()
      elapsed, start = elapsed.time - start, elapsed.time
      duration = duration - elapsed
    end
  end

To turn the ship smoothly, it will see what portion of the turn duration has just elapsed (maxing out at all of it), and turn by that large a slice of the remaining angle:

    while duration > 0 do
      local elapsed = coroutine.yield()
      elapsed, start = elapsed.time - start, elapsed.time
      local wedge = angle * math.min(1, (elapsed / duration))
      actions.face(actions.facing + wedge)
      duration = duration - elapsed
    end

Finally, it will reduce the remaining angle to turn by the amount it just turned by:

      actions.face(actions.facing + wedge)
      angle = angle - wedge
      duration = duration - elapsed
    end

Open game.lua and add the dogfighter module to the list of elements the game can create:

scene.Spawn = {
  turret = require "turret";
  dogfighter = require "dogfighter";
}

If you test the code at this point, you will see a ship fly down across the screen and bank, although it should not fire yet.

Save and move to the file ship.lua in the ship folder of your project directory. Find the section where it declares the fighter description, and fill a new entry into the Weapons table:

    MaxHealth = 1;
    Weapons = {
      MachineGun = weapon.MachineGun,
    };
  },
  dreadnought = ship {

If you test the code again, the enemy ship should fire as it comes down from the top of the screen.