SDK - Importing Custom Props

## Props

Props are non-avatar objects that can be interacted with while recording in-app. Their motion is recordable and exportable. Props can have simulated physics and more complex behaviors.

## Simple Props

   Simple props are objects that are either animated by being grabbed by the player, or otherwise by physics simulation. Physics and collider properties are defined in the SDK by Unity's built-in physics system. Props will collide with scene colliders when dropped. Props can have their physics enabled individually in-app. Props that don't have physics enabled will simply float wherever the player leaves them.

### Creating a Simple Prop

1. Drag the model into the scene (it can be a blend file or an fbx file)
2. In the **Inspector** panel, click **Add Component** and add the **APS\_SDK** script (you may use the search bar)
3. In the **type** dropdown, select **prop**
4. Click **Build Prop From FBX** (it may have a slightly different title depending on the filetype)
5. Transfer the prop folder to the VR\_MocapAssets folder

### Transferring the Built Prop to Mocap Fusion VR

The prop files are exported into the unity project, so there is one last step you must do every time you build or rebuild an prop.

1. Copy/Paste the avatar folder into the Mocap Fusion VR's **VR\_MocapAssets** folder, located at `%USERPROFILE%\AppData\LocalLow\Animation Prep Studios\LUXOR\VR_MocapAssets\`

The **.meta** files can be ignored.

### Configuring Physics

**Colliders** allow you to design the shape of the prop in relation to the physics system. It also defines the area from which a VR player may grab the object, which is necessary even for non-physics props.

The difference between the actual object's shape and the collider's shape is usually for performance reasons. Try to emulate the shape of the object with the basic collider shapes provided, or just use a mesh collider. See the official Unity manual on colliders for more info.

**Rigidbody** is where you define physics properties. See the official Unity manual on rigidbodies for more info.

### Grab Position

The **Grab Point Target** is generated when you first build the prop. Place it where you would naturally hold the prop. You will still be able to grip the prop from any point - this just changes the position that the prop spawns into your hand for convenience.

## Firearm Props

   Guns can be used in-app with physics-based bullets, sound effects, hit sounds, scopes, and more. Most of these features can be tweaked in the SDK.

*Note: Some firearm features, such as particles and sounds, are currently only available in Luxor. Only the contents of the original .fbx or .blend files ends up being exported to blender, so SDK-added attachments like the sniper scope do not currently transfer to blender.*

### Creating a Firearm Prop

* Build the Prop (see **Creating a Simple Prop**)
* In the **Prop Linker**, change **Asset Type** to **firearm**
* Click **Add Helpers**
* Tweak settings (see below)
* **Re-build Prop Asset** using the Prop Linker
* Transfer the prop folder to the VR\_MocapAssets folder

The prop is now ready, but can be tweaked.

### Firearm Helpers

#### FiringPoint

Sets the location from which bullets appear, and the direction in which they go. This also contains the **Firearm Linker** component, with various settings for in-app animation.

##### *Prefabs (Leave as-is)*

*These are just references to already-generated helpers. You shouldn't need to change these. See the objects themselves to tweak their settings.*

##### Muzzle Sounds FX

Set the sounds that will play when firing the firearm. You can add more than 1 sound by increasing the **Size** and adding multiple audio files. A random audio file from the list will be played each time the weapon is fired. Default sounds are included in the SDK.

###### Firing Sounds Near

The sound the firearm makes to nearby listeners.

###### Firing Sounds Distant

The sound the firearm makes to distant listeners (approximately 100 meters away). If the listener is between less than 100 meters away, both the near and distant sound effects will be mixed appropriately.

You can change the distance settings in the **AudioNear** and **AudioDistant** Audio Source components, located as separate objects inside the FiringPoint using Unity's built-in audio system.

###### Flybysound

The sound that is heard when the bullet itself passes very close to a listener. The fly-by sound radius can be set in the BulletPrefab, and is by default 5 meters.

##### Accessories sounds FX

###### Change Mode Clip

The sound that plays when the firing mode is changed (e.g. single to burst fire).

##### *Audio Sources (Leave as-is)*

*These are just references to already-generated helpers. You shouldn't need to change these for any reason.*

##### Bullet Forward Velocity

The speed, in meters-per-second, that the bullet will start moving at. This speed is set regardless of the mass of the bullet, so for heavy projectiles you may want to reduce this significantly.

##### Firing Rate

The delay between shots, while in **burst** or **auto** firing mode.

*Note: The performer can fire faster than the firing rate by repeated pressing the trigger button at a faster rate.*

##### Blood

The prefab that spawns when a bullet from this firearm hits a character.

##### Blood Audio Clips

The sound that plays when a bullet from this firearm hits a character.

##### Land Hit Explosion

The prefab that spawns when a bullet hits land. Any part of the scene that is not assigned the Water layer is considered land. When building a custom scene, the land must have colliders for projectiles to be able to impact on it.

##### Land Hit Audio Clips

The sound that plays when a bullet from this firearm hits land.

##### Water Hit Explosion

The prefab that spawns when a bullet hits water. Any part of the scene that is on the Water layer is considered land.

##### Water Hit Audio Clips

The sound that plays when a bullet from this firearm hits water.

##### On Scope Zoom Level Changed

This is an open-ended action that will take place in-app whenever the scope is changed. [Todo- should this be edited by user or is it overwritten in-app?]

##### Mode

Sets the mode that the firearm will fire.

* **Single**: 1 bullet will be fired each time the trigger is pulled, so long as time equal to the **Firing Rate** has passed.
* **Burst**: 3 bullet will be fired each time the trigger is pulled, with time equal to the **Firing Rate** passing between each fire.
* **Auto**: Unlimited bullets will fire so long as the trigger is held down, with time equal to the **Firing Rate** passing between each fire.

The mode can be changed in-game while holding the firearm using the Zoom binding (**B** by default)

##### *Trigger (Leave as-is)*

*This simply represents whether the trigger is being held-down, and used in-game. No change necessary.*

#### Sniper Scope

By default, a functioning sniper scope is added to your firearm. It is optional. To remove it, disable the SniperScope prefab. Otherwise, drag it to the appropriate location on the firearm. The default mesh (Bushnell\_TrophyXLT\_2-6x32) can be removed, so long as the **Camera** and **Render Surface** remain.

##### Cameras

This camera renders the view that will be displayed on the **Render Surface**.

##### Sniper Scope Controller

This component provides controls for tweaking the appearance and behavior of the scope. *For more information, hover over each field in the SDK itself.*

*Currently, the scope itself is not exported, and is only for use in-app.*

#### Muzzle Flash Particles

This is just an object that is activated each time the firearm fires. By default, it includes light and particle effects. The descendants of this object can be tweaked, moved, animated, or removed, or added to. For more information on designing muzzle flash effects, see the official Unity documentation on Particle Systems and Lights.

#### BulletPrefab and BulletTracerPrefab

Contains the actual model and effects that will be shot from the firearm, as well as the **Bullet Hit Set Inactive** component. Note that some settings on the component are redundant, such as audio files, which should be set from the **FiringPoint** component instead. [TODO: doublecheck that that is true]

##### Rigidbody

Sets the physics properties of the bullet. See the official Unity documentation on Rigidbodies.

*Note: The projectile mass can be changed in-app to various presets at any time.*

##### Box Collider / Colliders

Sets the area that determines whether the bullet has collided with a target.

Note that the default collider area is much larger than and offset in front of the bullet. This is to compensate for the high speed it travels at in unity's physics system. If your custom projectiles are large or slow, you will want to change the collider to match. See the official Unity documentation on Box Colliders.

##### Trail Renderer

This displays a trail behind the bullet that can be customized. You can drag the bullet around in the Unity editor to preview the trail. See the official Unity documentation on Trail Renderers.

##### Bullet Hit Set Inactive

This provides some settings for the bullet itself.

###### Hit Damage Amount

The damage this bullet will do to a character when it collides.

*Currently, characters die instantly, as this feature is still in development.*

###### Explosion Destroy Delay

If a generic explosion effect is set, this sets the amount of time, in seconds, before the effect disappears. This should be set to a longer duration than the longest particle effect.

This delay applies to all hit explosion effects (generic, land, and water)

###### Hit Explosion

This is a generic explosion effect that you can assign to be be spawned every time this bullet hits any target. This effect will spawn in addition to any other hit effects like blood splatter or water hits.

###### Bullet Life Seconds

The amount of time, in seconds, after being fired, that this bullet will exist. If the bullet lives this long without hitting anything, it will not generate any hit effects.

###### *Blood, Audio Clips, and specific Hit Explosions*

*[TODO: These seem to be redundant, and should be set in the FirearmLinker component instead]*

##### Bullet Player Proximity Sound

This provides additional settings for the sounds that play when bullet's whiz past a listener. (See Flybysound)

###### *Flybysound (Leave as-is)*

*This is a redundant setting and does not need to be changed.*

###### Radius

The radius, in meters, around the bullet that listeners must be inside to hear the Flyby-sound.

## Vehicle Props

Mocap Fusion supports physics-based vehicle controls for animating vehicle movement. These are also called **platforms**. Currently, the following types of vehicles controls are supported:

* VTOL
* Fixed Wing

    *Note that any vehicle prop can be used for any vehicle type.*

### Creating a Vehicle Prop

1. Build the Prop (see **Creating a Simple Prop**)
2. Ensure that the front of the vehicle is facing in the Z+ direction (blue arrow)
	1. You may need to rotate the model and apply rotation in blender
3. Place the Grab Position where the player will sit, approximately near the center of mass of the vehicle.
4. In the **Prop Linker**, change **Asset Type** to **vehicle**
5. **Re-build Prop Asset** using the Prop Linker
6. Transfer the prop folder to the VR\_MocapAssets folder

#### Collider Setup

The vehicle only needs some kind of landing gear, or collider at its very bottom, so that it can land on the ground. Wheel colliders can be used as landing gear, though they are unnecessary for VTOL vehicles.

There should also be a floor to the vehicle itself. For example, an airplane's cabin should have a floor.

The rest of the vehicle's frame should not have colliders.

#### Rigidbody Setup

The in-game simulation force values, such as thrust, cannot be edited. To adjust the way a vehicle behaves, change the rigidbody settings. Vehicles should have a higher mass, drag (movement resistance), and angular drag (rotation resistance) than the default rigidbody settings.

#### Using the Custom Vehicle

To load and pilot the custom vehicle in-app, see Vehicle Platforms

## Tutorials & External **Links**

https://www.mocapfusion.com/tutorials/adding-props

## Troubleshooting

### The prop's scale is wrong in-app

Re-scale the prop in unity, or apply the scale transform in blender and then rebuild the prop.

### The firearm's bullets are firing in the wrong direction

Ensure that the FiringPoint's Z+ axis (visible as the big white arrow) is pointing in the direction it should be firing in.

### The firearm's bullets are not colliding with anything

Compare your BulletPrefab with the default bullet and ensure that the collider is large enough, the rigidbody is attached, and the various bullet scripts are attached.

If you are using a custom scene, ensure that the scenery itself has colliders and is either set to static or has a rigidbody attached.

### The "Re-build" button isn't doing anything

The prefab can't be built in Unity's prefab editor. Drag the prefab into a scene and try again.