Basic Installation

To install the physBone API, simply add physBoneAPI.lua into your script. If you use autoScripts in avatar.json, add it there.

You can download physBoneAPI.lua in the physBone discord post or here on GitHub

Creating a PhysBone

To make a physbone, simply rename a blockbench group to include either physBone or physBoob as a prefix at the beginning of your group's name. For example, physBone1 or physBoneHat. This will convert this group into a physBone. With this done, it should work in-game right away! Make sure your physBone's pivot matches where you want your physBone to swing from!

It's also recommended you add a second group inside your physBone and put all your model parts in there. If you're working with meshes, this will be required or they will break (Figura bug). You will be unable to edit the pos / rot / scale of the physBone, and any immediate children of the physBone, but subsequent children will be fine.

Default Presets

physBone

Makes your physBone swing like a pendulum. This is the default physBone setting. Also supports PhysBone

physBoob

Makes your physBone springy, and move like breasts. Also supports PhysBoob

Debug Mode

You can enable debug mode in your avatar by pressing shift + ~. This view mode will show you where physBones are on your avatar, where they're pointing, how long they are, etc. This is extremely useful for debugging, and you will need to know how to access it.

Fixing Incorrect Length and Rotation

You may notice your physBone in debug mode doesn't match your model parts. It may be too long, or it may point in the wrong direction / be detached from your model.

To fix this, you can create a new group inside your physBone and include either boneEnd or BoneEnd as a prefix. For example, boneEnd1 or boneEndEar. Move your group until it's positioned at the tip of your physBone model. You may need to use ctrl + shift for precise movement.

Now if you enable debug mode, it should be aligned and the correct length!

If you notice your model is now rotated incorrectly in its roll axis, this can be easily fixed. Rotate the Y axis (green) of your boneEnd group, and this will roll your model that many degrees. You can correct for incorrect roll with this.

Applying a Spring Force

A spring force will make the physBone be attracted to the specified direction like a spring, and is how physBoob works. To create a spring force, make a new group inside your physBone with either springForce or SpringForce as a prefix. Move your group so that relative to your physBone pivot, it is in the direction your physbone will be pulled.

Now, rotate the Y axis of your springForce group to set the force you should pull your physBone with.

It should now pull your physBone in that direction! You can visualise the spring force in debug mode with the blue line. You can only have one springForce group per physBone.

Creating a Collider

Colliders act as obstacles for your physBones. They will not (usually) pass through them, and will bounce off them. You can create a collider my making a new cube inside your avatar, and incliding either collider or Collider as a prefix. E.g. collider1 or colliderBody. You must set a texture for this cube. It doesn't matter what texture, so its best just use a pre-existing one.

You can hide the collider in blockbench if you wish. In game, any physBones should now collide with your collider. If you enable debug mode, your colliders will be visible.

You can also disable collider faces, which can increase efficiency. Set your cube's UV mode to per-face, if it isn't already.

Then click on face properties on the top-right of the UV editor.

Here, you can disable faces by unchecking them. This will disable collision with those faces.

More advanced colliders will require setting up collider nodes