How to use

Before you can use the plugin you must do the following steps (we assume you already have a working ApertusVR on your computer, if you do not, check out our guide here).

Deploying the plugin

If ApertusVR is ready to use, make sure that the bullet library is installed through ApertusVR's cmake system. For this the APE_PLUGINS_BulletPhysics variable's checkbox must be checked in before generating, as you can see on the picture below:

If you watch the cmake gui carefully, you may notice that there's also two variable related to physics: APE_PLUGIN_PhysicsSimulationScene, and APE_SAMPLES_PhysicsSimulation. If you want to examine the samples, you need this two variable checked in too. Else you can try it in your own sample, after made one. To learn about making a sample, please read the following guide:

At this point we assume, that Bullet is deployed within ApertusVR, and you have a working sample. The next milestone is to get Bullet plugin usable in your sample. To reach this level of magnificence, please follow these five steps:

1. Open your sample's config folder at: \ApertusVR\samples\MySample.

2. Open the folder's of the config you attend to use with bullet plugin (\ApertusVR\samples\MySample\config\myconfig).

3. Open the CMakeLists.txt file you find in the folder and add the apeBulletPhysicsPlugin.json to set property, and save it.

4. Open the apeCore.json file in the same folder, and add the "apeBulletPhysicsPlugin"in the "plugins" attribute, and save it.

5. Open CMake gui, and click on the Generate button.

CMakeLists.txt
set (CONFIGS
    # other plugins config files ...
	apeBulletPlugin.json
	apeCore.json
	)
​
add_custom_target(
    Configs_mySample_myconfig ALL
    SOURCES ${CONFIGS}
)
​
set_property (TARGET Configs_mySample_myconfig PROPERTY FOLDER "Samples/MySample/Configs")

apeCore.json
{
  "plugins": [
    other plugins...,
    "apeBulletPhysicsPlugin"
  ],
  "network": {
    "user": "cave",
    "participant": "none",
    "internet": {
      "natPunchThrough": {
        "ip": "",
        "port": ""
      },
      "lobby": {
        "ip": "",
        "port": "",
        "room": ""
      }
    },
    "lan": {
      "ip": "",
      "port": ""
    },
    "selected": "none",
    "resourceLocations": [
      "/macros/sceneMaker/resources",
      "/plugins/assimpAssetLoader/resources"
    ]
  }
}

Creating rigid bodies for primitives

Now if everything is in order, you have a working sample with the Bullet plugin attached to it. For the most cases, when using ApertusVR we are designing our scene in a plugin too (sometimes with help of the SceneMakerMacro). Therefore we need a plugin to put our scene in it. If you aren't familiar with creating plugins for ApertusVR, please check this short guide, to became a professional plugin maker.

Hopefully when you've reached these lines, you have a sample with BulletPhysicsPlugin, and you also attached a plugin wich will contain the scene elements. Hence we can start to discuss how to use plugin on your scene. For this part, we presume that you're experienced with nodes and geometries in ApertusVR. If this isn't right, you can always check the related parts of the documentation:

The entity what is used by BulletPhysicsPlugin is somewhat similar to these two. ApertusVR has an entity called RIGIDBODY, which is responsible for positioning and orienting our geometry's node according to the laws of physics. We will discuss more detail about the RIGIDBODY entity in the Features section, for now it's enough that we know, it exists. The following code sample shows, how you can create RIGIDBODY for a specific geometry, wich in that case is a box (GEOMETRY_BOX).

if (auto boxNode = mpSceneManager->createNode("boxNode").lock())
{
		// creating geometry for box
		ape::BoxGeometrySharedPtr box;
		if (box = std::static_pointer_cast<ape::IBoxGeometry>(mpSceneManager->createEntity(name, ape::Entity::GEOMETRY_BOX).lock()))
		{
			box->setParameters(dims);
			box->setParentNode(boxNode);
		}
		
		// creating rigid body for box
		ape::RigidBodySharedPtr boxBody;
		if (boxBody = std::static_pointer_cast<ape::IRigidBody>(mpSceneManager->createEntity(name + "Body", ape::Entity::RIGIDBODY).lock()))
		{
			boxBody->setParentNode(boxNode);
			boxBody->setGeometry(box);
		}
}

Let's get through what we've done here. We made a node called boxNode, and immediately made a box geometry too. With this two entity, we have every necessary objects to make our rigid body. You can create it anyway, but it's not a big surprise that rigid bodies are only working properly if these two are attached to it. After reading this, you must be capable of making rigid bodies for primitve objects. However we don't always want to play only with boxes and spheres, or cones, do we? So now we'll move onto creating something more interesting than that.

Creating rigid bodies for meshes

For this cause we have an other plugin called apeAssimpAssetLoaderPlugin. This plugin provides support for wide range of mesh files, i.e. .gltf, .obj, or .stl. What is more great about this is that you can configure it easily by a json file, just like you do it with the other plugins. Thus you have a neat way for attaching rigid bodies to your geometry. You can inclue the Assimp plugin on the same way as the other plugins, so we assume that it doesn't make a big deal to handle it. Once you have Assimp in your sample, you can add the rigid body in the json file. The next code sample shows you, how to do it.

ApeAssimpAssetLoaderPlugin.json
{
  "assets": [
    {
      "file": "/plugins/assimpAssetLoader/resources/MyMeshFile.gltf",
      "mergeAndExportMeshes": false,
      "scale": [2,2,2],
      "position": [ 50,250, 10],
      "orientation": [  0.0007963, 0, 0.9999997, 0],
      "regenerateNormals": true,
      "rootNodeName": "suzanne",
      "physics": {
        "mass": 1.0,
        "restitution": 0.7,
        "friction": 0.5,
        "rollingFriction": 0.1,
        "spinningFriction": 0.1,
        "linearDamping": 0.01,
        "angularDamping": 0.05,
        "colliderType": "auto",
        "bouyancyEnabled": false
      }
    }
  ]
}

As you see, it couldn't be more simple, just set a "physics"property, and you're done with it. However you may noticed some other properties within the physics property. Those aren't necessary for creating the body, but we'll discuss them later in the Features section. Sometimes it occours that the user only wants a geometry without any physics properties attached to it. In that case just simply don't set any "physics" property in the asset's config, and then Bullet doesn't get any request for making body for you.

This is the end of the section about using the plugin, now you must be capable of making rigid bodies and attach it to your scene, even if it's a complex mesh geometry. We can move onto the next level: configuring the BulletPhysics plugin.