README for bale trailer modding (using BaleTrailer.lua script).

First, notice that the model (Gisebo_bvOne.i3d) and textures (under tex folder) of the Gisebo BV1 mod is copyrighted to the user 'bitten' at the LS-UK.info forum,
http://www.ls-uk.info/forum/index.php?action=profile;u=2168
Do not steal that material for usage as reskins, changes or whatever without prior permission!

The script BaleVehicle.lua made by me ('Aqualize', also active at ls-uk.info or at farmsim@aqualize.se) is licensed under the "Simplified BSD License". Please send an e-mail to tell me in what mod you have used it, it is not necessary but I'm curious if this script will get any spread.
See the license in the top of the script source file and wikipedia:
http://en.wikipedia.org/w/index.php?title=BSD_licenses&oldid=393307009#2-clause_license_.28.22Simplified_BSD_License.22_or_.22FreeBSD_License.22.29
But the last paragraph is removed as it is pointless for me (I'm the copyright holder but I'm also the author of the source file).

So what does it mean, simplified?
 - Don't use the model or textures without permission.
 - Please use the script to build cool mods and modify it if you want!



 
The rest of the text will focus on how to use the script for your own model, learning from how the Gisebo BV1 works.

1. Have a look in the modDesc.xml, notice the <specialization name="BaleVehicle" className="BaleVehicle" filename="Scripts/BaleVehicle.lua"/>.
	You need do similar in your modDesc.xml. Probably nothing new for anyone that have done mods before.

2.	Have a look in the Gisebo_bvOne.xml. The baleHandling tag in the end is the interesting part. This configures various things for the script.
	The attribute stackHandlingRootNode="17" tells the script it should look for certain things under the node 0|17 in the i3d model.
	Have a look there, if you expand the first root you will see the node "bale_handling" as the 18th item. Similar it is for "grab_and_drop_handling".

3.	When you create the model for your bale trailer you should in the i3d model (via GIANTS editor) place transformation groups for different tasks that the script uses.
		
	First thing to explain is: where will bales be placed?
		-	You place a number of transform groups (in our i3d file called "bale_box_#"). These should have the attributes depth, height and width.
			As a minimum each box should have 1x1x1 (thus it will be a single bale). If you add more you should know that they are placed on the positive sides of
			axles from the transform group you have assigned to be a bale box. Also it abides the rotation of the transform group. This gives you total control over
			how bales should be placed. Create as many bale groups as you want. Notice our trailer having the LHS column of bales being placed a bit differently.
		-	The distance between the bales is set in the xml file for the model (attributes to baleSpec_#) and is global to all bales of that specification (I think it 
			only supports using one bale specification now anyway). It has been tweaked to look good for small square bales.
	
	As you may have seen the loading process does not fill up the trailer with bales bottom-to-top but stacking them more like if a human was in the trailer doing that work.
	The magic between this is that a point in space relative to the trailer root of the bale boxes node is put as the "front". It then calculates the three dimensional
	distance to each of the bale attachment points (created out of the bale boxes) and starts with the attachment point furthest away. Thus it creates a loading order.
	It works similar for the unloading, just that it starts with the attachment point closest.
	
	There are also some grabBalePoint_# in the xml file for the model and grab_bales_... in the i3d file. These are the different areas from where you can let the 
	script scan for bales, within a given area (user attribute in the i3d file). Each grab point should correspond to a loading order point (they need to be the same number).
	It works similary for unloading points (but those don't need any radius). The bale will (should at least?) inherit the rotation of the transform group it uses.
	So you can rotate it to have bales drop down on their short side if that is for whatever reason desired.
	Drop bale points can also have animations. The animation is not the bale actually moving but a door or hatch may be opened first. See the side bar doors on our trailer.
	But know this: the animation thing in the script is a bit shaky, it doesn't always do the animation when it should. Sadly...
	
	IMPORTANT: All these changes you do the the i3d file are overwritten when you export a new model from whatever modelling program you use. To save it you should 
	open the i3d file in a good text editor (as notepad++) and copy it. Look how it is for our model. Open Gisebo_bvOne.i3d in a text editor and search for the text
	<TransformGroup name="bale_handling" nodeId="200">
	You recognize this, yes? It is the "stackHandlingRootNode", the 0|17 node. We copy that and the next 21 lines to some other text file. Go through it and replace each 
	nodeId with some large number but keep it relative for each other. So instead of nodeId="200" write nodeId="11200" and "11201" instead of "201" etc (adding 11 000).
	Also copy the last section <UserAttributes> and replace the nodeId similary.
	So when you next time export a new version of your model from your 3d modelling program perhaps you've added a few nodes, nodes which would conflict with our special
	numbers. Instead you copy the saved texts (place it in the right position so the references like 0|17 still holds) it will not conflict and when you save something in GIANTS
	it will automatically recalculate it so there isn't any gaps in the numbering of nodes. I have saved mine "in script nodes for i3d.txt" (but not adding 11 000).
	
Ok know you know the most important part of creating a mod using the BaleVehicle script (I hope). You can send me an e-mail at farmsim@aqualize.se and I might be of 
some help (but I don't have time to DO YOUR mod).


/ Aqualize