==============
USAF Orion Mod
version 0.20
==============

Updated to KSP 1.2 with much help (I basically did nothing) from HebaruSan and FreeThinker

Author: Winchell Chung nyrath@projectrho.com
Thanks to NovaSilisko, Oskar Gryting Vokac, Rhys Taylor, and Scott Lowther

Main thread:
http://forum.kerbalspaceprogram.com/showthread.php/28428-Orion-aka-Ol-Boom-boom

==============
INTRODUCTION
==============

This is an experimental mod for Kerbal Space Program that simulates an Orion Nuclear Pulse rocket.
http://www.projectrho.com/public_html/rocket/enginelist.php#id--Pulse--Orion
http://en.wikipedia.org/wiki/Project_Orion_%28nuclear_propulsion%29
http://www.astronautix.com/lvs/orion.htm

The primary source of data was this document
http://www.up-ship.com/eAPR/ev1n5.htm

==============
INSTALLATION
==============

Orion mod requires KSP version 1.04 or later. It will not work properly on earlier versions.

Unzip the archive

Inside the USAFOrionMod folder, find the GameData folder. Copy this folder into your Kerbal Space Program folder.
(in Windows, Steam version, this will be something like
C:\Program Files (x86)\Steam\SteamApps\common\Kerbal Space Program\
non-steam something like
C:\Program Files (x86)\Kerbal Space Program\
)

In more detail:
the folder \USAFOrionMod\GameData\Nyrath\ needs to be copied into your \Kerbal Space Program\GameData\folder

The \USAFOrionMod\USAFOrionReadMe.txt is this document you are currently reading.

The \USAFOrionMod\Extras\USAFOrionExtras folder is only for people who want to re-paint the engine, otherwise you can ignore it.

\USAFOrionMod\Source\USAFOrionSource is the source code for USAFOrion.dll, which is required to be released for security reasons.

==============
QUICK START
==============

Go to Vertical Assembly Building.
Select the Mk 1 Cockpit and drag it to the VAB. Click on it and use mouse wheel to move it way up near the ceiling.
Click CONTROL tab. Select Advanced S.A.S Module Large. Drag it to bottom of Cockpit til it clicks.
Click PROPULSION tab. Go to next page. Select UKAF Nuclear Pulse MultiMagazine 3.5MNx600. Drag it to bottom of SAS til it clicks.
Use mouse wheel to scroll down in VAB so you see bottom of Fuel Tank, do middle-click drag to back off from the rocket stack.
Select UKAF Nuclear Pulse Engine(there are two, you want the one WITHOUT the framework on the top). Drag it to bottom of Fuel Tank until it clicks.
Use mouse wheel to scroll down. Hold mouse wheel and move mouse to back away from engine, so you can see engine and the ground. Pusher plate base should be quite a bit above ground. If it is not high enough, select cockpit and move it higher.
Click STRUCTURAL tab. 
Click Symmetry button until you have 8 fold symmetry.
Select TT18-A Launch Stability Enhancer. Drag it to VAB. Move upward until they connect with the sides of the engine, very near the top, right under the magazines.
In the staging display to the right, ensure that the engine and the TT18-A are in the same stage segment
Give your ship a name.
Save it.
Click LAUNCH button

To the left in the staging display, next to the engine icon you will see NUKE:600. This means you have 600 bombs in your magazine. When they run out, your ship has no fuel. Please note the NUKE indicator will show zero even if the magazine has bombs, if you have inadvertently deactivated the magazine. Activate/deactivate by right-clicking on the Orion engine, and click the button next to 3.5kN until is says "feeding".

Click the shift key until the throttle is at about 50%

You might want to scroll the image back a ways from the ship.
WARNING: the first detonation will be really loud, turn down your speaker. I'm not sure why that happens. 
When you hit the space bar, the TT18-A will release, and one bomb will automatically detonate. Bombs will be set off at 1 second intervals. They detonate about 23 meters behind the pusher plate. With each detonation, the plate will be slammed up, gradually move down, when it all the way down the next bomb will go off.

Please note that the impulse from each bomb also impacts on the vessels "rigidbody". Translation: flimsy ships will be shaken apart. 

The pusher plate will gradually grow hot, but currently it does not seem hot enough to blow up the ship. I think.
The debris cloud will be left behind as long as you are in the atmosphere. Once out, the debris cloud will stay behind the ship.

Note that the Orion as configured can boost about 100 tons at 2 g. Since we only have a cockpit on top, you will notice savage shocks on the acceleration meter.

WARNING: the bomb detonations will damage other nearby ships. (Orion ship that launched the bomb is immune)
Other ships within 1200 meters of the detonation point will be inflicted with 1750 kiloNewtons of shock (decreasing with range).
Other ships within 240 meters of the detonation point will explode
As you lift off, you may notice the TT18-A struts exploding, since they are within 220 meters.

You might want to add an auxiliary propulsion system for docking to another ship or space station. Otherwise you will blow up what you are trying to dock to. 

It is possible to land on your plate, but it is difficult. You have to come down with a speed less than 100 m/s, and the bombs have an annoying granularity.

==============
IN MORE DETAIL
==============

The Orion changes the amount of its "thrust" by altering the delay between bomb bursts. The more closely spaced the bursts are, the more the ship will accelerate in each second.

With the throttle from 10% to 30%, the bombs will detonate at 1.5 second intervals.
30% to 60% the bombs will detonate at 1.15 second intervals
60% to 100% the bombs will detonate at 0.8 second intervals
(these intervals are taken from the USAF 10 meter Orion, that's why they are such odd values. They are set in the bomb magazine part.cfg file)
The effective thrust is equal to the bombImpulse divided by the engine's current detonation delay time.
For example, if you are using 3.5 MN bombs and the detonation delay time is detonationMinDelay (0.8 seconds), the effective thrust will be 
3,500 / 0.8 = 4,375 kiloNewtons


When the throttle is set to zero, individual bombs may be fired by tapping the Z key. This could be used if one is insane enough to try and touchdown under nuclear bomb power. Sort of like playing atomic Lunar Lander.

The Orion engine with no framework on the top is meant to be used with the UKAF Nuclear Pulse MultiMagazine 3.5MNx600, for quick Orion designs. It contains 600 nuclear bombs, each of which imparts 3,500 kiloNewtons (3.5 megaNewtons) with each detonation.

The Orion engine with the framework on the top is meant to be used with the mix-and-match individual magazines. You stack the magazines on one of the six stack points on the shoulders of the engine. There are six types of bombs, with impulses of 0.88 megaNewtons, 3.5MN, 10MN, 20MN, 80MN, and 400MN. The 3.5MN is the "standard" bomb, used by the USAF 10 meter Orion design. The 0.88MN is for fine maneuvering. The 80MN is an utterly ridiculous over-powered bomb, and the 400MN is completely over-the-top. Please note that the 0.88MN bombs are too weak to lift the Orion under Kerbin's gravity.

Having said that, the only difference between the two engines is the presence of the framework, and how high the center connection node is. You could use the no-framework engine with individual magazines, and put some sort of modular girder segment or something in the middle.

With individual magazines you can ensure you have precisely the right amount of bombs for your mission. The framework is sized to hold 60 magazines, but you can stack them higher if need be.

Warning! The individual magazines are quite massive. In the VAB, read the description of each magazine and note their mass. It is vitally important that you balance the magazines around the ship's thrust axis, or you will drastically shift the ship's center of gravity (in the VAB turn on the CG marker). You might have better attitude control by placing reaction control thrusters on the engine as opposed to using an SAS on the top.

Warning! All the bombs transmit a shock to whatever is in the stack of parts perched on top of the Orion. This is not much of a problem with the 3.5kN bombs, but the larger ones could shake parts off the ship. Use struts if necessary. If your ship blows up on the launch pad, attach about 8 struts in eight-fold symetry between the engine and the part resting upon it. Also inspect the mission log for any reports about two parts breaking apart. Attach struts between them and try again.

Warning! If your vessel is quite massive (say, with two or more 400MN magazines) it will be tippy, that it, the vessel will sway back and forth if it is resting on the ground on its pusher plate (with no launch struts or landing feet). If you try to lift off using the Orion engine, the vessel will explode. So if the vessel does not sway you can safely do a nuclear launch, but if it does sway you'd better have landing feet or launch struts.

Currently the magazines are magic. They do not have to be attached to the Orion engine, to each other, or connected with fuel ducts. As long as they are physically attached to the vessel, the engine can magically use them as a fuel source. This includes other vessels with magazines that are docked to the ship.

During a mission, right-clicking on a given Magazine will pop-up a list of properties for that magazine. The main property of interest is the number of bombs remaining. 

In the VAB, action groups can be set by selecting the Orion engine to turn on and off various bomb magazine types. Note that all types will be listed in the action groups, even if no magazine of that particular type is attached to the vessel. Also note that the 3.5 MN individual magazine is considered to be different from the 3.5 MN multimagazine.

Also of interest is the Damage zone and Destroy zone. With each bomb detonation, any vessel or space station that is not attached to the Orion but is within Damage Zone number of meters of the detonation point will be inflicted with (kN per bomb divided by 2) kiloNewtons of impulse, falling off with distance from detonation point. Anything not attached to the Orion within the Destroy zone will explode.

During a mission, right-clicking on the Engine will pop-up the magazine controls. This will only be useful if you have stacked magazines with different sizes of bombs and you wish to control which bomb type is used for the next burn.

Say your Orion has 3.5MN magazines and 0.88MN magazines. Upon being sent to the launch pad, all magazines types are automatically activated. When a bomb is launched, the engine examines all active magazines, and extracts a bomb from the magazine with the largest number of bombs. This is in an attempt to keep the vessel balanced as bombs are expended.

Trouble is, the 0.88MN bombs are too weak to lift the Orion under Kerbin gravity. The ship will fall down to the launch pad and blow up. You have to disable the 0.88MN magazines for the launch.

Right-clicking on the engine will show:
UKAF Nuclear Pulse Engine
0.88MN feeding (Kill->) []
3.5MN  feeding (Kill->) []
Show Xfer Menu []

This means both the magazine types are feeding the Orion engine. The "Kill" label is pointing at the button to the right. Click that button to kill the feed for that bomb type. You want to click the 0.88MN button, it will change to 
0.88 off (Start->) []
which means 0.88 magazine is currently deactivated, click the button to start it feeding again.

As magazine types are turned on and off, "Nuke:nnnn" display in the staging display will change to show the effective number of available bombs. The display turns red if there are zero nukes available. 
This means if during a mission the display shows "Nuke: 0" when you know there are still nukes left, right-click on the engine to be sure all the magazines are turned on.

These menus are dynamic. This means if a user creates a brand new type of magazine, it will automatically appear in the pop up menu (if that type of magazine is used on the current vessel). Note that currently you are limited to 10 total types of magazines in your Parts folder, only the first 10 will appear in the menu.

When two or more ships with Orion magazines are docked together it is possible to transfer bombs between them. This will allow an Orion bomb tanker to fly out to an Orion ship with empty magazines and fill it up.
In order to transfer bombs of a particular type, both docked ships must have at least one magazine of that type. A magazine can only hold so many bombs (usually 60), if it is full up with bombs you cannot transfer any more into it. Currently due to complications, you cannot transfer 3.5MN bombs from a 3.5MN magazine into a 3.5MN array, even though both the magazine and array use the same type of bomb. I am working on fixing that.
 
When you transfer a bomb, the bomb is automatically taken from the fullest magazine of that bomb type on the source ship and moved to the emptiest magazine on the destination ship. This is an attempt to keep the ships balanced, since each bomb is about a ton. 

To transfer, right-click on the Orion engine of either docked ship to make the bomb menu appear. At the bottom is Show Xfer Menu. Click the button to the right of this to make the Nuke Transfer window appear.
Each docked ship will have its own column. At the top is the name of the ship (currently only one ship will have a name, the others will be "Docked #1" etc.). Next is the "Use" control, click the use controls for the two ships involved with the transfer. Lastly is one or more bomb type buttons. Each button will show the total number of bombs of that type on the ship. 

Clicking on a bomb button (when the "use" control at the top of the column is set) will transfer that type of bomb from the ship named at the top of the column, to the other ship with its "use" control set.

When done, banish the Nuke Transfer window by clicking the "X" at the upper right, or clicking Hide Xfer Menu in the bomb menu. 

I have tried using decouplers with the bomb magazines, but they insist upon explosively decoupling while the ship is on the launch pad.

==============
TWEAKING THE MOD
==============

TEXTURES

Some people dislike the textures I supplied. In the USAFOrionExtras folder are image files to assist you in editing the textures.
The actual textures are in the Part\USAFOrionEngine folder and Part\USAFOrionMagazine folder 
They are MBM files. Edit them with the instructions found here:
http://wiki.kerbalspaceprogram.com/wiki/Editing_MBM_Textures

A user who goes by the handle TurboNisu has made an alternate set of textures. They are in the USAFOrionExtras folder in OrionTexturePack_v1.zip, including installation instructions.

PARTS.CFG

A lot of the parameters for the engine are exposed in the two parts.cfg files. This means you can tweak the engine quite a bit to your taste. Be warned that tweaking it too far may have unexpected results. And always make a backup copy of the original files. Edit the files with your favorite text editor, but be warned that I have heard some text editors make the files so KSP cannot load them. Probably something about changing the CR characters in to CR/LF or something like that. I use Notepad++

Tweaking USAFOrionEngine
------------------------

For test purposes I have mass=30 even though it should be mass=91. 30 is "Kerbal size"

Apparently maxtemp=4000 is not low enough for the engine to ever overheat. Though I have noticed the magazine start to glow in an ominous fashion.

"plateOffsetCompressed" is how far the pusher plate moves upward above neutral point when slammed by nuclear detonation, determined by Unity3d mesh model. Leave this alone.

"plateOffsetExtended" is how far the pusher plate moves downward below neutral point when recoiling, determined by Unity3d mesh model. Leave this alone

"bombStartY" is the starting position of a given nuclear pulse unit relative to the origin point of the Unity3D mesh model of the engine. Generally it is where the bomb unit is hidden inside the mouth of the bomb launching cannon. The bomb will start here, and be animated to travel downward through the pusher plate in transit to detonation point. Leave this alone.

"plateCycleTime" is the time in seconds taken by entire pusher plate animation cycle

Note about pusher plate animation:
(Segment 1) Plate starts in Neutral position. A bomb moves from the mouth of the cannon, through the center of the pusher plate, reaching the detonation point. There it explodes. Detonation point is at z = plateBottomY + detonationDeltaY 
(Segment 2) Upon bomb detonation, plate moves upward plateOffsetCompressed meters. 
(Segment 3) At maximum upward offset, plate reverses direction and moves downward to Neutral position. 
(Segment 4) When Neutral is reached, the plate continues moving downward plateOffsetExtended meters. 
(Segment 5) At maximum downward offset, plate reverses direction and moves upwards to Neutral position. 
When Neutral position is reached, that is the end of the animation.
Plate moves sinusoidaly, that is, it moves fastest the nearest it is to the neutral position, and gradually slows down as it reaches the maximum upper and lower positions.

The entire animation takes plateCycleTime seconds.
The USAFOrion.dll plug in takes the above values to calculate the plates motion in meter per second, which is used to time the various segments such that the entire animation takes plateCycleTime seconds.


"detonationMinDelay" delay in seconds between bomb detonations when throttle is set from 100% to 60% or Z key is used.
"detonationStdDelay" delay in seconds between detonations, when throttle is set from 60% to 30%. Must be longer than detonationMinDelay
"detonationMaxDelay" delay in seconds between detonations, when throttle is set from 30% to 10%. Must be longer than detonationStdDelay

Do not make any of the detonation delays less than plateCycleTime

Note: the effective thrust is equal to bombImpulse of the magazine used divided by the detonation delay used. For example, if the 3.5MN magazine is used with detonationMinDelay (0.8 seconds), the effective thrust will be 3,500 / 0.8 = 4,375 kiloNewtons

"plateTopY" is determined by the Unity3D mesh model, leave this alone. It is the distance between center of vessel and "top" of pusher plate (as a negative number). "Top" is defined as where the pusher plate shock absorbers enter the button of the main body of the engine. Any other part that is attached to the engine, and is located between plateTopY and plateBottomY, will move up and down with the pusher plate animation.

"plateBottomY" is determined by the Unity3D mesh model, leave this alone. It is the distance between center of vessel and bottom of pusher plate (as a negative number)

"detonationDeltaY" is how far below the pusher plate the explosion take place at. Currently this is set to -23 which is 23 meters below the bottom edge of the pusher plate, because this is  what the USAF Orion used.

"engineModelName" is the name of the Unity3D model, leave this alone.
"subModelPlateName" is the name of the pusher plate sub model in the Unity3D model, leave this alone.
"subModelBombName" is the name of the nuclear pulse unit sub model in the Unity3D model, leave this alone.
If you are substituting your own Unity3D model, make sure it has a separate pusher plate part and a bomb part, and edit the values for node_stack_top, node_stack_bottom, ThermalAnim, plateOffsetCompressed, plateOffsetExtended, plateTopY, plateBottomY, engineModelName, bombStartY, subModelPlateName, and subModelBombName

"explosionGroupPower" is the power setting for the FXGroup special effect of the bomb blast
"fxmongerHowHard" is the howHard setting for the FXMonger.Explode() call that creates the bomb blast

Module BombXferWindow handles the bomb transfer dialog

Tweaking USAFOrionMagazine
--------------------------

bomb table from Orion documents
 0.863 kt with     880 kiloNewtons = 0.077 tons
 1 kt     with   2,000 kiloNewtons = 0.079 tons
 1 kt     with   3,500 kiloNewtons = 0.141 tons
 5 kt     with  80,000 kiloNewtons = 1.152 tons
15 kt     with 400,000 kiloNewtons = 1.153 tons


"bombTitle" is the title that appears in pop-up menu for activating magazines

"bombStockpile" is the number of bombs you start with. Be warned that the bombs increase the mass of the ship. The 3.5MN magazine contains 90 bombs, all the others contain 60.

"bombImpulse" is the amount of kiloNewtons imparted by each bomb blast. The effective thrust is equal to the bombImpulse divided by the engine's current detonation delay (see "Tweaking USAFOrionEngine" above)
This is also the amount of shock inflicted on the ship's rigidbody
You can find suggested values from the bomb table above

"bombMass" is the mass of one single bomb in tons
You can find suggested values from the bomb table above

"dryMass" is the mass of the magazine when it is totally empty. The 3.5MN magazine has a dryMass of 0.6486, the other magazines have a dryMass of 0.18

The magazine starts out with a wet mass of (bombStockpile * bombMass) + dryMass
As the number of bombs goes down, so does the magazine mass

"bombHeat" is the temperature increase per bomb detonation. Currently arbitrarily set to 200, via experimentation and watching how fast the plate heated up.

"damageZone" is the range in meters from the bomb detonation within which other ships will be inflicted with shock damage. The Orion ship is immune from its own bombs. On the launch site this is capable of blowing other ships over the horizon.
This is arbitrarily set to atmospheric ground burst with 1 psi of overpressure (moderate damage to civilian buildings)
1.1 kilometers for a  0.863 kiloton device
1.2 kilometers for a  1 kiloton device
2.0 kilometers for a  5 kiloton device
2.9 kilometers for a 15 kiloton device

"damageShock" is how much shock damage ships will suffer if they are inside the damage zone
for lack of a better number, I arbitrarily set damageShock to bombImpulse/2.0

"destroyZone" is the range in meters from the bomb detonation within which other ships will explode. The Orion ship is immune from its own bombs.
This is arbitrarily set to atmospheric ground burst with 15 psi of overpressure (urban areas completely levelled)
240 meters for a  0.863 kiloton device
240 meters for a  1 kiloton device
418 meters for a  5 kiloton device
612 meters for a 15 kiloton device

For overpressure values you can use
http://meyerweb.com/eric/tools/gmap/hydesim.html
don't forget to convert miles into meters

"destroyMass" is a refinement. Any given part caught within destroyZone of a bomb detonation will explode UNLESS that part has a mass larger than destroyMass. This was added when a tester inadvertently set off a nuke and accidentally destroyed the asteroid Roche.

KNOWN BUGS
--------------------------
When you change focus to a new Orion ship, all of its magazines will be set to feed.
The thrust, delta V and other parameters do not currently appear in such mods as MechJeb.

CHANGELOG
--------------------------
VERSION 19
Updated to deal with KSP v1.0.4.  Note: This update doesn't fix the right click menu for sorting pulse unit selection, but using control groups still works.  

VERSION 18
Bug fix: with KSP version 0.21 Orion vessels were blowing up on the launch pad. With the fix, they no longer explode unless the ship is "tippy" and has no launch struts or landing legs. "Tippy" is defined as a ship massive enough so if it is resting on its bare pusher plate it will gently sway back and forth.

VERSION 17
Added mechanism for two docked Orion ships to transfer bombs

VERSION 16
added animation of little bomb dropping through the pusher plate

VERSION 15
parts attached to pusher plate now will move up and down with the plate.
Pusher plate animation is now sinusoidal instead of linear.
In VAB, Orion engine has action groups to turn on and off various magazine types

VERSION 14
Dynamic menu on Orion Engine. All magazine types (including user created ones) will appear in menu if used on a given vessel. Max 10 magazine types.
Flags were added to the side of the Orion engine
Pusher cycle animation
Added 20MN magazines
Removed 2MN magazines
Made 3.5MN magazines contain 60 bombs, instead of 92
Lowered the mass of the 40MN magazines

VERSION 13
Engine with tower restructured with holes in magazine bay, so now parts can be attached to support column
fixed bug in virtual mass (magazines were still at full mass
Added 10MN magazines

VERSION 12
Mod restructured to KSP 0.20 format
"atomic clamps" set to unlock if magazine is undocked.
"virtual mass" implemented to try and stop magazines from chattering.


VERSION 11
restored the masses of the 5kt80mn and 15kt400mn magazines, and instead increased the mass of the Orion engine to 30

VERSION 10
drastically reduced the mass of the 5kt80mn and 15kt400mn magazines in an attempt to keep them from chattering like Mexican jumping beans

VERSION 09
Added destroyMass when a playtester inadvertently destroyed Roche.
Other ships within damageZone have their parts increase in temperature by bombHeat.
Magazines no longer need struts to attach them to engine.
Switching to another vessel then back to Orion caused unexpected bomb detonation. Fixed.
Quicksaving caused unexpected bomb detonation. Fixed.
Bug fix: if you turn off all bomb magazines, turn on throttle, then turn on a magazine, no nukes are fire.
"atomic clamps" implemented to try and stop magazines from chattering.

				

