Karma Reference

Document Summary: A comprehensive reference for the Karma properties.

Original Author was James Golding. ( jamesg@epicgames.com )
Updated by Chris Linder ( DemiurgeStudios^? ) on 6-10-2003 to update for 2226.
Updated by Chris Linder ( DemiurgeStudios^? ) on 7-9-2003 to add more robust comments for StayUprightStiffness and StayUprightDamping.
Updated by Chris Linder ( DemiurgeStudios^? ) on 8-5-2003 to add more robust comments for KInertiaTensor.

Note - this reference is for 2226 based builds of the Unreal Engine, NOT for UT2003. Much of this information will be useful for UT2003 but there are some small differences.

For additional information about Karma see also:

ImportingKarmaActors

UsingKarmaActors

ExampleMapsKarmaColosseum

CollisionTutorial

KarmaAuthoringTool

Karma User Guide: KarmaUserGuide.pdf

Contents

Removing Karma Integration

If you don't want to use Karma physics at all, you can stop the integration being compiled in by commenting out the line:

#define WITH_KARMA

in Engine/Inc/Engine.h, and rebuilding everything. You will also find a metoolkit_dummy directory which contains empty, null karma libraries. So if you rename this directory to metoolkit it will link against these instead of the real ones, which could save you some space.

Introduction

Karma is a rigid-body physics engine that has been integrated into the Unreal engine from version 829. It allows you to simulate solid objects such as crates, tyres or bones, as well as different joints, motors or springs between objects. Using these simple 'building blocks', complicated systems can be easily built that will behave according to the laws of physics. This can be anything from the classic stack of crates, to swinging lights or doors that can be shot off their hinges, up to 18-wheeler trucks, or characters falling down stairs like a rag-doll when they die.

This document briefly covers the fundamentals of using Karma in Unreal. For lots more useful information on using Karma in a game, please have a look at the Karma Developers Guide.

If you experience any problems using Karma, do check the UW.log file for any warnings including the world 'Karma'. These can give very useful information about any potential problems.

Note: Karma does not cover other types of physics, such as fluid, cloth, smoke, deformable bodies etc.

There are 3 ways to use Karma in the Unreal engine. We will come back to each of these cases in more detail later.

• Level Physics - This covers systems set up entirely inside the Unreal Editor, that don't require any specialized control. For example, placing crates or barrels around a level, or hanging a chandelier from the ceiling. This type of physics can be set up without writing any UnrealScript.

• Vehicle Physics - This covers a system which is placed as one 'unit' in the level, and has specialized UnrealScript code for controlling it. In this case, a new UnrealScript class is created for the vehicle, which will spawn all the parts it needs when the game starts.

• Rag Doll Physics - This is refers to using Karma to simulate a skeletal mesh as if it were a collection of bones joined together. This allows much more interesting death sequences such as players tumbling down stairs, or ending up slumped across furniture. To use this description of the physics of the skeleton (mass of each bone, joint limits etc.) needs to be created and assigned.

Enabling Karma

To use Karma physics to drive the motion of any Actor, you use the new physics type PHYS_Karma. However, to get it to behave as you want, you will need to set a few things up.

Karma Collision

Although it is possible to generate contacts directly from triangle meshes, given the high poly counts this is not a very efficient option. Instead, a set of 'collision primitives' (spheres, boxes, cylinders and convex hulls) are fitted to static meshes for Karma contact generation.

A utility has been built into the .ASE importer in UnrealEd for Static Meshes for generating this collision information. When creating the graphics for your static mesh (e.g. inside MAX), also create the desired collision primitives. The name of each collision primitive must start with a keyword to identify what it is:

(see the Create in a Modeling Program part of the CollisionTutorial for more information about creating collision primitives)

When you import this .ASE into UnrealEd, you will be asked if you want to store the collision geometry with the static mesh inside the .usx package. When viewing static meshes in the static mesh browser, those that have collision geometry/mass information stored with them are shown with a '*' prefixed.

Each named part will be converted into Karma collision geometry (if possible), and removed from the graphics. A default inertia tensor and centre-of-mass position is also calculated for this static mesh and stored. The collision geometry, inertia-tensor and centre-of-mass position are automatically re-scaled if the Actors DrawScale is changed. For line-checks (e.g. shooting the static mesh), Unreal's triangle-accurate tests are still used by default. This however can be changed by altering the settings of the static mesh. (see the "Collision Models" section of CollisionTutorial for more details.)

There is also support for colliding against parts of the level not constructed using static meshes with collision geometry. Terrain collision works by querying the heightfield to find just the set of triangles underneath the Actor, and passing these to Karma's triangle-primitive collision system. This will also ignore 'invisible' parts of the terrain used for tunnels etc, and will take into account 'flipped' triangles. For BSP collision, the BSP is queried to find a set of potentially-colliding triangles, and these are put together with any terrain triangles before being passed to Karma to generate contacts. Generating good contacts from arbitrary collections of triangles is potentially difficult, so static-meshes with simplified collision geometry usually produce better results.

Please note that if you are using PHYS_Karma, you will probably need to disable the usual Unreal collision. This is because Karma may well try to move the Actor into a position which Unreal would not normally allow (e.g. two chairs with legs interlocking). For more on Actors using Karma blocking players see Player Interaction below.

Physics Parameters (KParams)

Parameters used by Karma when simulating an Actor are stored in the KarmaParams structure (or one of its sub-classes). If you simply place KActor objects in a level using the right-click menu, they will use a KarmaParams with default values of these properties. Below is a description of what they mean.

KarmaParams

Base class. Contains general properties.

KarmaParamsRBFull

Subclass of KarmaParams. Assigning one of these to an Actor instead of a basic KarmaParams allows over-riding the default static mesh physics properties for this Actor.

KarmaParamsSkel

Subclass of KarmaParams. Used specifically for Actors using RagDoll physics.

Physics Volumes

Actors simulated using Karma will use the gravity specified by the Physics Volume they are currently in.

Player Interaction

Having the player interact with Karma simulated actors is a subtle area. There are three main types on interaction.

Shooting

This works at the moment. The default behavior for each Actor derived from KActor is to have an impulse applied to the point where the shot hit.

Pushing

Having the player interact directly with other Karma Actors is a little more difficult. Currently players can be pushed around by Karma Actors and that is all. More complex interaction such as see-saws and jumping onto stacks can be added in the future.

Manipulating

Currently there is no direct support for the user picking up and moving other Karma Actors. However, there are special constraint types that allow a player to pick up and manipulate objects (making stacks etc.), and these could be exposed in the future as needed.

Joints

There is a special class of Actor used to join other Actors together in different ways - the KConstraint class. A 'constraint' is just some relationship that will be enforced between two Actors, or between one Actor and the world. This includes joints, but can also cover springs, motors, sliders etc.

Below KConstraint in the Actor Browser you will find several joint types that can be used (more will be added in the future). Here are the parameters common to all constraint types.

Joint Types

Some parameters are specific to particular joint types. Also, the orientation of the constraint may be important, depending on the type of constraint.

Ball And Socket (KBSJoint)

This simply pins a point on one Actor to a point on another. There are no parameters to set up.

Cone Limit (KConeLimit)

The cone limit isn't really a joint; it is used for adding limits to other joints by restricting the angle between them (KHalfAngle). For example, you could add hard stops to a swing door, or prevent a lampshade swinging more than 45 degrees from the vertical.

Hinge (KHinge)

As well as acting as a simple hinge, it can be used as a spring or a motor. This is defined by the KHingeType parameter. The options are:

The parameters that are used to configure the hinge are given below.

The 'controlled' option uses a simple controller to drive the hinge motor to a particular angle. This is useful for driving pieces of machinery (cranes etc.). It does this by setting the desired velocity for each timestep to achieve the desired orientation. If the current error is more than KProportionalGap, the velocity will be KDesiredAngVel. Once the error is between 0 and KProportionalGap, the velocity will slowly ramp down until it achieves the desired angle.

KHinges can be also be triggered in the same way as movers etc. By setting the initial state of the KHinge, different behaviors can be achieved.

Car Wheel Joint (KCarWheelJoint)

This is a specialized type of joint used for connecting wheels to vehicles, and allows you so set up suspension, steering and drive. The steering works in the same way as the KHinge constraint HT_Conrolled mode.

Debugging

There are several very useful console commands that are very useful for figuring out what exactly is going on with your simulation:

You can also toggle these options using the Debug Menu (press 'Esc').

It is worth checking the UW.log file regularly, especially if you are having problems, as this can contain useful warnings.

Creating Good Simulations With Karma

Take a look at the 'Creating Good Simulations With Karma' chapter in the Karma User Guide (page 85) for lots of useful information.

Known Issues

• Currently there is a hard limit on the number of objects (about 200) that can be simulated at the same time. This is due to memory considerations, and should be made more flexible in the future.

• The swept check when moving Karma actors is imperfect. So if you have a very small Actor, moving very fast, it can pass straight through a wall and will not be detected. This will be improved in the near future.