Add 4 API functions

API.md

@@ -0,0 +1,36 @@
+# `pride_flags` API
+
+Programmers can use the following Lua functions to add custom flags,
+get a list of all flags, and set and get the flag of flag pole nodes.
+
+## Functions
+
+### `pride_flags.add_flag = function(name)`
+Add a new flag to the game. `name` is the flag identifier.
+There *must* exist a texture with the name `prideflag_<name>.png`.
+The texture *should* have an aspect ratio of 1.3.
+The recommended size is 78×60, but other sizes are OK
+as long the aspect ratio is respected.
+
+The flag name *must not* already exist. This will be checked.
+
+On success, the flag will be appended to the list of flags at the end.
+
+If a flag with the given name already exists, no flag will be
+added.
+
+Returns `true` on success and `false` on failure.
+
+### `pride_flags.get_flags = function()`
+Returns a list of all available flag identifiers. The flags
+are sorted by selection order.
+
+### `pride_flags.set_flag_at = function(pos, flag_name)`
+Sets the flag at an upper mast node at position `pos` to the flag `flag_name`.
+The node at `pos` *must* be `pride_flags:upper_mast`.
+Returns `true` on success and `false` otherwise.
+
+### `pride_flags.get_flag_at = function(pos)`
+Returns the currently used flag at the upper mast node at position `pos`.
+The node at `pos` *must* be `pride_flags:upper_mast`.
+Returns a string on success and `nil` otherwise.

README.txt

@@ -54,6 +54,11 @@ These flags are available:
 * Queer
 	* Queer
 
+API (for programmers)
+----------------------
+This mod has a few helper functions if you're a programmer and want to interface with it.
+You can add custom flags and more. See `API.md` for a list of all functions.
+
 Repository
 ----------------------
 

init.lua

@@ -5,6 +5,8 @@
 -- Copyright (c) 2022, Leslie E. Krause
 --------------------------------------------------------
 
+pride_flags = {}
+
 local wind_noise = PerlinNoise( 204, 1, 0, 500 )
 -- Check whether the new `get_2d` Perlin function is available,
 -- otherwise use `get2d`. Needed to suppress deprecation
@@ -61,8 +63,10 @@ local flag_list = {
 	-- queer
 	"queer",}
 
-local next_flag = {}
+local next_flag, prev_flag
-local prev_flag = {}
+local update_next_prev_flag_lists = function()
+	next_flag = {}
+	prev_flag = {}
 	for f=1, #flag_list do
 		local name1 = flag_list[f]
 		local name0, name2
@@ -79,15 +83,21 @@ for f=1, #flag_list do
 		next_flag[name1] = name2
 		prev_flag[name1] = name0
 	end
+end
+update_next_prev_flag_lists()
+
+local flag_exists = function(flag_name)
+	return next_flag[ flag_name] ~= nil
+end
 local get_next_flag = function(current_flag_name)
-	if not current_flag_name or not next_flag[ current_flag_name ] then
+	if not current_flag_name or not flag_exists( current_flag_name ) then
 		return DEFAULT_FLAG
 	else
 		return next_flag[current_flag_name]
 	end
 end
 local get_prev_flag = function(current_flag_name)
-	if not current_flag_name or not prev_flag[ current_flag_name ] then
+	if not current_flag_name or not flag_exists( current_flag_name ) then
 		return DEFAULT_FLAG
 	else
 		return prev_flag[current_flag_name]
@@ -619,3 +629,56 @@ minetest.register_node( "pride_flags:upper_mast_hidden_2", {
 	diggable = false,
 	floodable = false,
 })
+
+-- API
+pride_flags.add_flag = function( name )
+	if flag_exists( name ) then
+		return false
+	end
+	table.insert( flag_list, name )
+	update_next_prev_flag_lists()
+	return true
+end
+
+pride_flags.get_flags = function( )
+	return table.copy( flag_list )
+end
+
+pride_flags.set_flag_at = function( pos, flag_name )
+	local node = minetest.get_node( pos )
+	if node.name ~= "pride_flags:upper_mast" then
+		return false
+	end
+	if not flag_exists( flag_name ) then
+		return false
+	end
+	local node_idx = minetest.hash_node_position( pos )
+	local aflag = active_flags[ node_idx ]
+	local flag
+	if aflag then
+		flag = aflag:get_luaentity( )
+	end
+	if flag then
+		local set_flag_name = flag:reset_texture( flag_name )
+		if set_flag_name == flag_name then
+			local meta = minetest.get_meta( pos )
+			meta:set_string("flag_name", flag_name)
+			return true
+		end
+	end
+	return false
+end
+
+pride_flags.get_flag_at = function( pos )
+	local node = minetest.get_node( pos )
+	if node.name ~= "pride_flags:upper_mast" then
+		return nil
+	end
+	local meta = minetest.get_meta( pos )
+	local flag_name = meta:get_string("flag_name")
+	if flag_name ~= "" then
+		return flag_name
+	end
+end
+
+