My favorites | Sign in
Project Home Downloads Wiki Issues Source
How to create a mission.
Updated Jul 5, 2010 by


NAEV uses a mission system to give meaning to the game experience. Missions tell stories and enrich the game world. They are written in the Lua programming language using a customized API. This page describes missions in simple terms and provides some links to other resources.

Mission Types

They are primarily two types of missions:

Computer Missions are found at the Mission Computer. The player has complete control about whether to accept them or not. Computer Missions are generally randomly generated and have simple goals like delivering cargo or transporting passengers.

Other Missions can be picked up in other parts of the game. While an initial dialog may appear without warning, the player often has the chance to accept or decline a mission like this.

Aside from the Mission Computer, at the moment missions can pop up in any of the following places

  • Bar
  • Outfitters
  • Shipyard
  • Commodity Market
  • Or when the player lands

Mission Basics

Because of the flexibility of Lua and the NAEV Lua API, missions can be simple or extremely complex. They can end almost as soon as they begin, or take the player traveling throughout the galaxy.

When a mission starts a dialog usually pops up with some descriptive text. Usually the mission description explains some goal, which the player must achieve, such a winning a space battle, or traveling to another location. Often cargo will be loaded into the player's cargo hold. Many missions also have a time limit.

When a mission finishes, it may have a lasting effect on the game by paying the player money, increasing the player's standing with a game faction, or enabling other missions and game content.

Technical Details

Missions are indexed in an xml file found at in dat/mission.xml in the NAEV directory. An individual mission's Lua data is found in subdirectories under dat/missions/. The two are connected through a <lua> tag in the mission.xml file.


A sample mission tag in the mission.xml file would look a bit like this:

 <mission name="Example 2">
   <unique />
   <done>Example 1</done>
   <planet>Some Planet</planet>

Mission Skeleton

This is the skeleton of a Mission's Lua code. A file like this defines what happens in a mission, in what order, and under what conditions.




-- localization stuff, translators would work here
lang = naev.lang()
if lang == "es" then
else -- default english
   text = {}
   text[1] = "some text"

--[[ Create the mission with the create() functions OBLIGATORY
-- This is a Computer Mission so we dont run the accept() function here. 
-- We define strings for reward/desc/title which are what appears
--    sees the mission in the computer.
function create
   misn.setReward( string.format( misn_reward, reward) )
   misn.setDesc( misn_desc)
   misn.setTitle( misn_title)
   misn.setMarker( a_system, "misc" )

--[[ Accepts the mission - OBLIGATORY for mission computer.
function accept()
   if nothing_needs_toBe_done ~= true then

function something()
   tk.msg( "more happens here")


Some of the functions in the mission skeleton above are NAEV Lua API calls. The interface with the guts of the NAEV program, which is written in C, allow mission writers to control a number of aspects of the game.

Lua scripted missions can create text-filled windows with the Tk widget toolkit. They can create and manipulate in-game pilots, including the player's ship. The API can load the player's vessel up with cargo and remove it. API functions can define time limits, and save variables in the player's pilot file, for later use. Of course, the Programming Interface also enables missions to gather a lot of information about the game state. Check out the NAEV Lua API page for detailed information on everything that can be done. You can also create it locally using the make docs command at the shell prompt in the root directory of the NAEV git repo.

On the other hand functions in the mission file can also be defined in the script itself. Lua mission files give missions writers access to the broad range of Lua language features and supported programming paradigms.

In a real mission, the Lua skeleton defined above would be filled out further with the strings, programming logic, and data structures that make missions interesting. Missions are endlessly flexible and accommodate a much creativity as the mission maker can concieve.

Comment by, Apr 8, 2010

I'm terrible at programming (all I know is basic HTML/CSS), but I'd really love to help out with developing storylines. Is there a simpleton way to contribute in this way?

As for writing itself (not creating missions ie, what the player needs to do), I could edit an .XML doc no problem, but I can't seem to find it on my NAEV windows install. Seriously, I'd love to contribute to this awesome game.

Comment by project member, Jul 3, 2010

@endger The "simple way" is generally to post a concept you want to work on the mailing list for example, like an overview of a short mission or something. Then you just take the advice you may get and start hacking. We can answer questions/doubts on the mailing list and on ircand when it's done it gets included. It's a pretty simple process.

Sign in to add a comment
Powered by Google Project Hosting