Expand addStructure() and changePlayerColour() functions (#3202)

* Expand js function capabilities

* Add comment over magic number

* A few small changes

addStructure() now takes the direction argument as an int instead of a float.
Added lines in functions.md and wzapi.cpp to clarify that the direction argument is optional.

doc/js-functions.md

@@ -268,8 +268,9 @@ looks, or to add variety to the looks of droids in campaign missions. (3.2+ only
 
 ## changePlayerColour(player, colour)
 
-Change a player's colour slot. The current player colour can be read from the ```playerData``` array. There are as many
-colour slots as the maximum number of players. (3.2.3+ only)
+Change a player's colour slot. The current player colour can be read from the ```playerData``` array. Available colours
+are green, orange, gray, black, red, blue, pink, cyan, yellow, purple, white, bright blue, neon green, infrared,
+ultraviolet, and brown, represented by the integers 0 - 15 respectively.
 
 ## setHealth(object, health)
 
@@ -769,11 +770,12 @@ Limit the scrollable area of the map to the given rectangle. (3.2+ only)
 
 Get the limits of the scrollable area of the map as an area object. (3.2+ only)
 
-## addStructure(structureName, player, x, y)
+## addStructure(structureName, player, x, y[, direction])
 
 Create a structure on the given position. Returns the structure on success, null otherwise.
 Position uses world coordinates, if you want use position based on Map Tiles, then
 use as addStructure(structureName, players, x*128, y*128)
+Direction is optional, and is specified in degrees.
 
 ## getStructureLimit(structureName[, player])
 

src/component.cpp

@@ -63,7 +63,8 @@ bool setPlayerColour(UDWORD player, UDWORD col)
 		NetPlay.players[player].colour = MAX_PLAYERS;
 		return true;
 	}
-	ASSERT_OR_RETURN(false, col < MAX_PLAYERS, "Bad colour setting");
+	// Allow color values from 0 to 15
+	ASSERT_OR_RETURN(false, col < 16, "Bad colour setting");
 	NetPlay.players[player].colour = col;
 	return true;
 }

src/wzapi.cpp

@@ -568,8 +568,9 @@ bool wzapi::replaceTexture(WZAPI_PARAMS(std::string oldFilename, std::string new
 
 //-- ## changePlayerColour(player, colour)
 //--
-//-- Change a player's colour slot. The current player colour can be read from the ```playerData``` array. There are as many
-//-- colour slots as the maximum number of players. (3.2.3+ only)
+//-- Change a player's colour slot. The current player colour can be read from the ```playerData``` array. Available colours
+//-- are green, orange, gray, black, red, blue, pink, cyan, yellow, purple, white, bright blue, neon green, infrared,
+//-- ultraviolet, and brown, represented by the integers 0 - 15 respectively.
 //--
 bool wzapi::changePlayerColour(WZAPI_PARAMS(int player, int colour))
 {
@@ -2977,20 +2978,23 @@ scr_area wzapi::getScrollLimits(WZAPI_NO_PARAMS)
 	return limits;
 }
 
-//-- ## addStructure(structureName, player, x, y)
+//-- ## addStructure(structureName, player, x, y[, direction])
 //--
 //-- Create a structure on the given position. Returns the structure on success, null otherwise.
 //-- Position uses world coordinates, if you want use position based on Map Tiles, then
 //-- use as addStructure(structureName, players, x*128, y*128)
+//-- Direction is optional, and is specified in degrees.
 //--
-wzapi::returned_nullable_ptr<const STRUCTURE> wzapi::addStructure(WZAPI_PARAMS(std::string structureName, int player, int x, int y))
+wzapi::returned_nullable_ptr<const STRUCTURE> wzapi::addStructure(WZAPI_PARAMS(std::string structureName, int player, int x, int y, optional<int> _direction))
 {
 	int structureIndex = getStructStatFromName(WzString::fromUtf8(structureName.c_str()));
 	SCRIPT_ASSERT(nullptr, context, structureIndex >= 0 && structureIndex < numStructureStats, "Structure %s not found", structureName.c_str());
 	SCRIPT_ASSERT_PLAYER(nullptr, context, player);
 
+	uint16_t direction = static_cast<uint16_t>(DEG(_direction.value_or(0)));
+
 	STRUCTURE_STATS *psStat = &asStructureStats[structureIndex];
-	STRUCTURE *psStruct = buildStructure(psStat, x, y, player, false);
+	STRUCTURE *psStruct = buildStructureDir(psStat, x, y, direction, player, false);
 	if (psStruct)
 	{
 		psStruct->status = SS_BUILT;

src/wzapi.h

@@ -1084,7 +1084,7 @@ namespace wzapi
 	bool removeObject(WZAPI_PARAMS(BASE_OBJECT *psObj, optional<bool> _sfx));
 	no_return_value setScrollLimits(WZAPI_PARAMS(int x1, int y1, int x2, int y2));
 	scr_area getScrollLimits(WZAPI_NO_PARAMS);
-	returned_nullable_ptr<const STRUCTURE> addStructure(WZAPI_PARAMS(std::string structureName, int player, int x, int y));
+	returned_nullable_ptr<const STRUCTURE> addStructure(WZAPI_PARAMS(std::string structureName, int player, int x, int y, optional<int> _direction));
 	unsigned int getStructureLimit(WZAPI_PARAMS(std::string structureName, optional<int> _player));
 	int countStruct(WZAPI_PARAMS(std::string structureName, optional<int> _playerFilter));
 	int countDroid(WZAPI_PARAMS(optional<int> _droidType, optional<int> _playerFilter));