Update the train copy/paste tool to include more wagon data.HEADmaster

- Copy additional wagon properties.
- Copy the wagon livery string set by the bike painter tool.
- Add support for optional custom functions in the wagon
  prototype so that the tool can can handle mod specific
  custom data, such as livery information.

2 files changed, 76 insertions, 6 deletions

diff --git a/advtrains/api_doc.txt b/advtrains/api_doc.txt
index faaac7c..a1eea92 100644
--- a/advtrains/api_doc.txt
+++ b/advtrains/api_doc.txt
@@ -129,6 +129,21 @@ advtrains.register_wagon(name, prototype, description, inventory_image)
 	^- optional: Function that is called whenever the train's velocity changes or every 2 seconds. Used to call 'self.object:update_animation()' if needed.
 	^- for compatibility reasons the name 'update_animation' for this function is still supported. 
 
+	custom_copy_from_wagon_to_clipboard() = function(wagon) end
+	^- optional: This is only used by the copy/paste tool to allow wagons that have custom data (such as livery information) to have their data be included in the copy operation.
+	^- This function must also be defined if paste_to_wagon_from_clipboard() is defined, otherwise neither function will be called.
+	^- The wagon parameter is a value from the advtrains.wagons[] table representing an exising wagon in the train being copied by the copy/paste tool.
+	^- This function should return a Lua value (a bool, string, integer or table as needed) that will be passed to the paste_to_wagon_from_clipboard() during the paste operation.
+	paste_to_wagon_from_clipboard() = function(wagon, custom_info)
+	^- optional: This is only used by the copy/paste tool to allow wagons that have custom data, such as livery information, to have their data be included in the paste operation.
+	^- This function must also be defined if custom_copy_from_wagon_to_clipboard() is defined, otherwise neither function will be called.
+	^- The wagon parameter is a value from the advtrains.wagons[] table representing the new wagon that is being created by the copy/paste tool.
+	^- The custom_info parameter is the value that was returned by the custom_copy_from_wagon_to_clipboard() for the wagon during the copy operation.
+	^- This function does not need to return a value.
+	^- Note: advtrains does nothing with custom_info other than pass it to paste_to_wagon_from_clipboard(). It can contain any data that is needed.  Mod authors should be aware,
+	^- however, that although unlikely, players can delete their wagons in between the copy and paste operations and so should avoid passing and using references to the source
+	^- wagon via custom_info. Improper handling of this situation will lead to a crash during the the paste operation. To be safe, custom_info should always contain a copy of the
+	^- needed data from the source wagon.
 }
 
 # Notes on wagons
diff --git a/advtrains/copytool.lua b/advtrains/copytool.lua
index cdfbd2e..7e12045 100644..100755
--- a/advtrains/copytool.lua
+++ b/advtrains/copytool.lua
@@ -1,4 +1,4 @@
---clipboard = {trainlen = number, [n] = {type = string, flipped = bool, }
+--clipboard = {trainlen = number, [n] = {type = string, flipped = bool, properties = {}, bike_painter_livery = string, custom_info = <optional custom data>}
 
 -- Yaw is in radians. There are 2pi rad in a circle. North is the 0 point and the angle increases anticlockwise.
 -- 4.712389 = 1.5pi; sin(1.5pi) = -1
@@ -63,10 +63,30 @@ minetest.register_tool("advtrains:copytool", {
 
 			local wagons = {}
 			local n = 1
-			for _, wagonProto in pairs(clipboard.wagons) do
-				local wagon = advtrains.create_wagon(wagonProto.type, pname)
-				advtrains.wagons[wagon].wagon_flipped = wagonProto.wagon_flipped
-				wagons[n] = wagon
+			for _, clip_data in pairs(clipboard.wagons) do
+				wagons[n] = advtrains.create_wagon(clip_data.type, pname)
+				local wagon = advtrains.wagons[wagons[n]]
+				wagon.wagon_flipped = clip_data.wagon_flipped
+
+				-- Paste relevant wagon properties
+				wagon.whitelist = clip_data.properties.whitelist
+				wagon.roadnumber = clip_data.properties.roadnumber
+				wagon.fc = clip_data.properties.fc
+				wagon.fcind = clip_data.properties.fcind
+
+				-- Paste bike painter livery information
+				if clip_data.bike_painter_livery then
+					wagon.livery = clip_data.bike_painter_livery
+				end
+
+				-- Paste any optional custom data
+				if clip_data.custom_info then
+					local wagon_proto = advtrains.wagon_prototypes[wagon.type or wagon.entity_name]
+					if wagon_proto and wagon_proto.custom_paste_to_wagon_from_clipboard then
+						wagon_proto.custom_paste_to_wagon_from_clipboard(wagon, clip_data.custom_info)
+					end
+				end
+
 				n = n + 1
 			end
 
@@ -124,11 +144,46 @@ minetest.register_tool("advtrains:copytool", {
 			local wagon = advtrains.wagons[wagonid]
 			clipboard.wagons[n] = {
 				wagon_flipped = wagon.wagon_flipped,
+				properties = {
+					-- Copy relevant wagon properties
+					whitelist = wagon.whitelist,
+					roadnumber = wagon.roadnumber,
+					fc = wagon.fc,
+					fcind = wagon.fcind,
+				},
 				type = wagon.type
 			}
+
+			-- Copy bike painter livery information
+			if wagon.livery and type(wagon.livery) == "string" then
+				-- As a convenience for older wagon mods, copy the livery string that can be set
+				-- by some mods that support using the bike painter. Note that this will result in
+				-- incomplete or missing livery information being copied for some mods that use
+				-- additional fields for livery information. In general, all mods that support
+				-- customizing liveries should provide the necessary implementations of
+				-- custom_copy_from_wagon_to_clipboard() and custom_paste_to_wagon_from_clipboard()
+				-- in their wagon's prototype to support their liveries being properly copied with
+				-- this tool. It is beyond the scope of advtrains to support livery schemes defined
+				-- in other mods.
+
+				-- As with code that supports the bike painter elsewhere in advtrains, this code
+				-- should be considered temporary since it may be removed in the future.
+				clipboard.wagons[n].bike_painter_livery = wagon.livery
+			end
+
+			-- Copy any custom data (for liveries or other uses) if defined in the wagon's prototype
+			local wagon_proto = advtrains.wagon_prototypes[wagon.type or wagon.entity_name]
+			if wagon_proto and wagon_proto.custom_copy_from_wagon_to_clipboard and wagon_proto.custom_paste_to_wagon_from_clipboard then
+				-- Use wagon_proto.custom_copy_from_wagon_to_clipboard() and
+				-- wagon_proto.custom_paste_to_wagon_from_clipboard() if and only if both are
+				-- defined. They should always be defined in tandem for a wagon when custom liveries
+				-- or other mod specific data need to be copied by this tool. The content of
+				-- custom_info is not relevant to the copy tool. It is treated as a "black box".
+				clipboard.wagons[n].custom_info = wagon_proto.custom_copy_from_wagon_to_clipboard(wagon)
+			end
+
 			n = n + 1
 		end
-		
 
 		local function flip_clipboard(wagon_clipboard)
 			local flipped = {}