improve scripting support for waypoint lists

1. Add an explicit `mn.createWaypointList` function
2. Allow `mn.createWaypoint` to be used with an empty waypoint list
3. Update documentation of `mn.createWaypoint` to clarify optional arguments

Author: Goober5000

code/ai/aicode.cpp

@@ -3534,6 +3534,13 @@ void ai_start_waypoints(object *objp, int wp_list_index, int wp_flags, int start
 		wp_list = find_waypoint_list_at_index(wp_list_index);
 	}
 
+	if (wp_list->get_waypoints().empty())
+	{
+		Warning(LOCATION, "Waypoint list '%s' is empty!", wp_list->get_name());
+		aip->mode = AIM_NONE;
+		return;
+	}
+
 	auto wp = find_waypoint_at_index(wp_list, start_index);
 	if (!wp)
 	{

code/object/waypoint.cpp

@@ -411,7 +411,7 @@ void waypoint_add_list(const char *name, const SCP_vector<vec3d> &vec_list)
 	Assert(wp_list.get_waypoints().size() <= 0xffff);
 }
 
-int waypoint_add(const vec3d *pos, int waypoint_instance)
+int waypoint_add(const vec3d *pos, int waypoint_instance, bool first_waypoint_in_list)
 {
 	Assert(pos != NULL);
 	waypoint_list *wp_list;
@@ -426,22 +426,28 @@ int waypoint_add(const vec3d *pos, int waypoint_instance)
 		waypoint_find_unique_name(buf, static_cast<int>(Waypoint_lists.size()) + 1);
 
 		// add new list with that name
-		waypoint_list new_list(buf);
-		Waypoint_lists.push_back(new_list);
+		Waypoint_lists.emplace_back(buf);
 		wp_list = &Waypoint_lists.back();
 
 		// set up references
 		wp_list_index = static_cast<int>(Waypoint_lists.size()) - 1;
 		wp_index = static_cast<int>(wp_list->get_waypoints().size());
 	}
-	// create the waypoint on the same list as, and immediately after, waypoint_instance
+	// create the waypoint on the same list as, and immediately after, waypoint_instance (unless it's the first waypoint)
 	else
 	{
 		calc_waypoint_indexes(waypoint_instance, wp_list_index, wp_index);
 		wp_list = find_waypoint_list_at_index(wp_list_index);
 
-		// theoretically waypoint_instance points to a current waypoint, so advance past it
-		wp_index++;
+		if (first_waypoint_in_list)
+		{
+			wp_index = 0;
+		}
+		else
+		{
+			// theoretically waypoint_instance points to a current waypoint, so advance past it
+			wp_index++;
+		}
 
 		// it has to be on, or at the end of, an existing list
 		Assert(wp_list != NULL);

code/object/waypoint.h

@@ -97,7 +97,7 @@ void waypoint_add_list(const char *name, const SCP_vector<vec3d> &vec_list);
 
 // Attempts to create a waypoint with the specified instance (used to calculate list and index).
 // Returns the object number, or -1 on failure.  Used by scripting and FRED.
-int waypoint_add(const vec3d *pos, int waypoint_instance);
+int waypoint_add(const vec3d *pos, int waypoint_instance, bool first_waypoint_in_list = false);
 
 // Removes a waypoint, including its entire list if it's the last waypoint remaining.
 void waypoint_remove(const waypoint *wpt);

code/scripting/api/libs/mission.cpp

@@ -1472,28 +1472,74 @@ ADE_FUNC(createDebris,
 	return ade_set_args(L, "o", l_Debris.Set(object_h(obj)));
 }
 
+ADE_FUNC(createWaypointList, l_Mission, "[string name]",
+	"Creates a waypoint list.  If a name is not specified, the list will have a default name.  Be sure to populate the list with at least one waypoint before using it!",
+	"waypointlist",
+	"Waypoint list handle, or invalid handle if waypoint list couldn't be created")
+{
+	char buf[NAME_LENGTH];
+	const char* name = nullptr;
+	if (!ade_get_args(L, "|s", &name))
+		return ade_set_error(L, "o", l_WaypointList.Set(waypointlist_h()));
+
+	// use either a specified name...
+	if (name)
+	{
+		auto list = find_matching_waypoint_list(name);
+		if (list)
+		{
+			Warning(LOCATION, "Waypoint list '%s' already exists!", name);
+			return ade_set_error(L, "o", l_WaypointList.Set(waypointlist_h()));
+		}
+		if (strlen(name) > NAME_LENGTH - 1)
+		{
+			Warning(LOCATION, "Waypoint list name '%s' must be at most %d characters!", name, NAME_LENGTH - 1);
+			return ade_set_error(L, "o", l_WaypointList.Set(waypointlist_h()));
+		}
+		strcpy_s(buf, name);
+	}
+	// ...or a generated name
+	else
+	{
+		waypoint_find_unique_name(buf, static_cast<int>(Waypoint_lists.size()) + 1);
+	}
+
+	// add new list with that name
+	Waypoint_lists.emplace_back(buf);
+	return ade_set_args(L, "o", l_WaypointList.Set(waypointlist_h(static_cast<int>(Waypoint_lists.size()) - 1)));
+}
+
 ADE_FUNC(createWaypoint, l_Mission, "[vector Position, waypointlist List]",
-		 "Creates a waypoint",
+		 "Creates a waypoint.  If Position is not specified, the waypoint will be at (0,0,0).  If List is not specified, a new list will be created and the waypoint will be added to it.",
 		 "waypoint",
 		 "Waypoint handle, or invalid waypoint handle if waypoint couldn't be created")
 {
-	vec3d *v3 = NULL;
-	waypointlist_h *wlh = NULL;
+	vec3d *v3 = nullptr;
+	waypointlist_h *wlh = nullptr;
 	if(!ade_get_args(L, "|oo", l_Vector.GetPtr(&v3), l_WaypointList.GetPtr(&wlh)))
 		return ade_set_error(L, "o", l_Waypoint.Set(object_h()));
 
-	// determine where we need to create it - it looks like we were given a waypoint list but not a waypoint itself
+	// determine where we need to create it - if we were given a waypoint list, put it at the end
+	// (unless the list is empty, in which case put it at the beginning)
 	int waypoint_instance = -1;
+	bool first_waypoint_in_list = false;
 	if (wlh && wlh->isValid())
 	{
 		int wp_list_index = wlh->wl_index;
-		int wp_index = static_cast<int>(wlh->getList()->get_waypoints().size()) - 1;
+		int wp_index;
+		if (wlh->getList()->get_waypoints().empty())
+		{
+			wp_index = 0;
+			first_waypoint_in_list = true;
+		}
+		else
+			wp_index = static_cast<int>(wlh->getList()->get_waypoints().size()) - 1;
 		waypoint_instance = calc_waypoint_instance(wp_list_index, wp_index);
 	}
-	int obj_idx = waypoint_add(v3 != NULL ? v3 : &vmd_zero_vector, waypoint_instance);
+	int obj_idx = waypoint_add(v3 != nullptr ? v3 : &vmd_zero_vector, waypoint_instance, first_waypoint_in_list);
 
 	if(obj_idx >= 0)
-		return ade_set_args(L, "o", l_Waypoint.Set(object_h(&Objects[obj_idx])));
+		return ade_set_args(L, "o", l_Waypoint.Set(object_h(obj_idx)));
 	else
 		return ade_set_args(L, "o", l_Waypoint.Set(object_h()));
 }