==============================================
QQuix - Rock, rock, rock your ship
Apr/2011 - Version 3.03 (see Version History)
==============================================

1. SHORT DESCRIPTION
=========
Ships and boats will rock with the wind improving the ambience in dock areas.


2. DESCRIPTION
===============
Ships and boats will rock slowly or fast according to the current weather's wind speed. Fog weather has the slowest wind. Thunderstorm weather, the fastest.

Ships in Anvil and IC Waterfront will rock automatically.
In other port areas included by mods, you may drop a provided Portable Breeze, so ships there will rock too.
There is also a Heavy Barrel that, when dropped on a ship's deck will unbalance the ship and make it rock.

Cargo, as barrels and crates, furniture, and lamps will rock with the ship.

===IMPORTANT===
Read before deactivating the mod: removing this mod without the proper steps may leave tilted ships all over.
To avoid this, before removing the mod, collect all the Portable Breezes. When you pick up the Portable Breeze crate it stops the movement and place all controlled ships and boats in the area back in their original vertical position.

But if you did remove the mod without taking the above steps, don't despair. Follow the ship reset procedure described in the next section.

If you have a previous version, please deactivate it before activating v3. Follow the instructions for deactivating it, or the ships will remain tilted and tilted ships are ignored and will not rock. Or, at least theoretically, you could have both versions active at the same time. If this is your choice and it does not work, let me know and I will fix it.

===DISCLAIMER===
This mod is meant to give ambience to dock areas. From close distance, some technical restrictions will be noticed (clipping)

3. USAGE

There are three carriable items: a Portable Breeze, a Heavy Barrel and a Ship Reset crate.

Besides some Portable Breezes already deployed, there are additional items in containers by the central lamp post in Anvil dock. The vertical one on the top contains Portable Breezes and Heavy Barrels, the one at the bottom contains Ship Reset crates.

Portable Breeze
Drop it anywhere in a port area. Grab and position it in a place of your choice and activate it once (space bar).
The first activation 'releases' the breeze and ships start rocking. The crate will remain where it is.
A second activation traps the breeze back in the crate and places the crate in your inventory, stopping the movements and resetting the ships to their original position.
There are some small crates already deployed and these will auto-release the breeze the first time the player gets close. They may be found in:
- Anvil dock: by the central lamp post close to the rowboat
- IC Waterfront: by the exit to the houses (right behind you when you fast travel)
- Wherever there is a rowboat in the wilderness in the original game (about 7).
Portable Breezes from the Anvil container are in larger crates, but the size of the crate does not affect its functionality in any way.

Heavy Barrel
Has the same function as the Portable Breeze, but operates on a single ship.
Drop it anywhere on the ship deck. Grab and position it someplace out of the way and activate it once (space bar).
The first activation 'unbalances' the ship and it starts rocking. The barrel will be moving with the ship and, during the movement, you cannot move it from its place (but you can activate it).
Activating the barrel while the ship is moving places it back in your inventory, stopping the ship movements and resetting it to its original position.

Ship Reset crate
Use in case you removed the mod and ships remained in tilted positions.
Get it from the crate in Anvil dock and drop it near tilted ships.
When you activate it, it will locate all ships in the area that were tilted by the mod and reposition them in their vertical position.
This process may take a couple of seconds and the crate will go to your inventory. You can, then, reuse it in some other area. When all ships are back in place, you may safely deactivate the mod.


Supported Ships
The mod will rock only preselected ships. These ships are hardcoded within the mod, so the scripts can identify, from the hundreds (?) of objects around the player, what is a ship and what is not (so they don't end up rocking the houses around the dock)
The supported ships are (from whatever mod that adds them):
- The original game ship [BloatedFloat01 Base Object]
- The original game rowboat [RowBoat01 Base Object]
- mr_siika's Cog [CogHull01.nif]
- mr_siika's fishing boats [MiddleBoatIdle01.nif and MiddleBoatSail01.nif]
- mr_siika's Corvettes [Corvette01.nif, Corvette01armed.nif, Corvette01armedfolded.nif and Corvette01folded.nif]
- mr_siika's Elven Galleys [ElvenGalleyHull01.nif and ElvenGalleyHull02.nif]
- mr_siika's Elven Swan boats [ElvenSwanShip01.nif and ElvenSwanShip02.nif]
- Reneers Sailing Mod's Pirate ship [RenShip02_test.nif]
- CLShade Sailboats [middleboatsailPC02.nif]
- Side's Sailing Ships [Cog01Body.nif, PirateShip.nif, CorvetteBody.nif, MiddleBoatBody.nif, ElvenGalleyBody.nif ElvenSwanBodyB.nif and MiniSwanBody.nif]

These are considered the basic ship meshes and any unmovable object (statics, containers, furniture, doors and lights) on them will rock together as one.

Exclusions: (these will not rock)
Any unsupported ship.
Any supported ship that is found already tilted in any way.
Any supported ship that is not at water level.
Any shallow boat that is not high enough on the water that tilting it would make its floor go below water.
Any supported ship that moves is reset and excluded.


4. TECHNICAL COMMENTS AND ISSUES
=========================
I have, finally, figured out the math to tilt a group of objects as one.
SkyRanger-1 provided the initial math to determine the XYZ positions of the parts.
While working on another project, developed the math to detect if other objects are inside the 'box' of the main object and I (finally) figured out the math to set the angles of the parts (if they are not originally tilted).

When the player first enters one of the selected areas or activates the breeze, the mod detects the ships and boats in the surrounding cells and, then, detects any objects that is within their mesh 'box' in order to build a 'set' of objects that will be tilted together. This process is heavy on the PC and may halt the game for a couple of seconds, but only runs once per area.

This mod was initially intended for other modders to use as a resource, so the script is coded in such a way that if more than one mod uses the same code, only one will 'take over' any given ship.

The script checks if the boat angles are as they were set in the previous frame. If different, it is assumed the boat has been tilted by another mod and will be ignored from then on (removed from the list). This is intended to allow more than one mod to use this same script without incompatibilities.

There will be some clipping at the feet of PC/NPCs on the ships, because the movement occurs only visually. The floor collision remains static.

The improved resetting mechanism adds information to your save game. This information is used to reset the ships to their original location. Once the ships are reset, this extra data is removed.

No known bugs.


5. COMPATIBILITY
================
Incompatible with mods that alters the Anvil docks or IC Waterfront in a way that turns inaccessible any object added by this mod.
Please let me know of any incompatibilities so I can either add a workaround or mention it here.

This version does not add rowboats to the Anvil docks anymore, in order to reduce incompatibilities.


6. REQUIREMENTS
=================
OBSE 0018 or above - (http://obse.silverlock.org)

. . .

9. CREDITS
==========
SkyRanger-1 for the initial math
Qazaaq for the instruction on how to create carriable crates and barrels in Blender.
The OBSE team for the invaluable functions that make this kind of mod possible

. . . .

13. VERSION HISTORY
====================
Version 1.0 - Jan 2010 - Initial release
Version 1.1 - Jan 2010 - Added checks to ignore boats that are not at water level or are tilted in any way.
Version 2.0 - Jan 2010 - Added the math to rock multi-objects as one, in order to rock ships and cargo.
Version 2.1 - Feb 2010
- Added the capability to start-stop the movement of the ships
- Added a recovery function to reposition selected ships and boats to their (hardcoded) vanilla positions.
Version 3.0 - Feb 2010
- Added the portable versions of the rocking scripts
- Removed the rowboats present in previous versions
- Added several new supported ships
- Improved the ship resetting mechanism
Version 3.01 - Feb 2010
- Fixed bug in the reset procedure
Version 3.02 - Feb 2010
- Added the meshes missing in 3.0 and 3.01
Version 3.03 - Apr 2011
- Added a workaround to avoid a CTD caused by a glitch on the GetSelf function.