 |
|
 |
|
|
|
Please take note! For mod developers working with Unreal Tournament 2003, this documentation is meant to be a starting point for your own explorations into UT2003, not a definitive guide. There will be differences between the documentation here and the product in your hands, and you may have to figure out quite a bit for yourself. Check out the Unreal Tournament 2003 page in the Unreal Powered area for links to community sites if you're having problems. UDN is a licensee support site, and cannot provide technical support or game-specific assistance to end users.
|
|
|
|
|
 |
KarmaReference |
 |
|
|
|
|
|
Licensees can log in.
Interested in the Unreal engine? Check out the licensing page.
Questions about UDN itself? Contact the UDN Staff.
|
|
|
|
|
|
|
|
|
|
Last Edited by James Golding. ( jamesg@epicgames.com )
WORK IN PROGRESS!!!
Note - this tutorial is for an earlier build of the Unreal Engine, NOT for UT2003. I will update the documentation as soon as I get a chance!
See also:
KarmaExample1
KarmaExample2
ImportingPhysicsAssets
Karma User Guide: http://udn.epicgames.com/Content/KarmaReference/KarmaUserGuide.pdf
- Karma - Reference
- Contents
- Removing Karma Integration
- Introduction
- Level Physics
- Vehicle Physics
- Rag Doll Physics
- Overview
- Karma Collision
- Physics Parameters
- KarmaParams
- KarmaParamsRBFull
- KarmaParamsSkel
- Physics Volumes
- Player Interaction
- Shooting
- Pushing
- Manipulating
- Joints
- Joint Types
- Ball And Socket (KBSJoint)
- Cone Limit (KConeLimit)
- Hinge (KHinge)
- Car Wheel Joint (KCarWheelJoint)
- Debugging
- Creating Good Simulations With Karma
- Known Issues
If you dont 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.
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.
This covers systems set up entirely inside the Unreal Editor, that don't require any specialised control. For example, placing crates or barrels around a level, or hanging a chandlier from the ceiling. This type of physics can be set up without writing any UnrealScript.
This covers a system which is placed as one 'unit' in the level, and has specialised 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.
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 tumlbing 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.
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.
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:
| MCDBX | Box Primitive |
| MCDSP | Sphere Primitive |
| MCDCY | Cylinder Primitive |
| MCDCX | Convex Mesh Primitive |
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.
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 produces 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.
Parameters used by Karma when simulating an Actor are stored in the KarmaParams structure (or one of its sub-classes). If you place 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.
Base class. Contains general properties.
| | Default |
|---|
| KMass | Mass of Actor used by Karma. | 1 |
| KLinearDamping | Amount of force applied to reduce linear motion of Actor. Like Drag. | 0.2 |
| KAngularDamping | Amount of foce applied to reduce angular motion of Actor. | 0.2 |
| KFriction | Used to calculate friction at contacts. 0 is frictionless, somwhere between 0 and 1 is a good start. | 0 |
| KRestitution | Posh word for 'bouncyness'. 0 is none, 1 is incoming velocity = outgoing velocity. | 0 |
| KImpactThreshold | Impact velocity at which KImpact UnrealScript event is triggered. | 100000 |
| KStartEnabled | Whether this Actor should start simulating as soon as it is spawned. | False |
| KStayUpright | Whether this Actor should use a constraint to keep its orientation upright. | False |
| KAllowRotate | Only valid if KStayUpright is True. Allow Actor to rotate about z axis. | False |
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.
| | Default |
|---|
| KInertiaTensor | Mass distribution of Actor - indicates how easily it can be spun. This is the 'identity' inertia tensor, for an object with a KMass of 1 and a DrawScale of 1. It will be scaled internally if KMass or DrawScale are changed. | 0.4 (diagonal) |
| KCOMOffset | Centre-off-mass position of Actor, relative to the static mesh origin. This is for a DrawScale of 1; it will be scaled internally if DrawScale is changed. | 0, 0, 0 |
Subclass of KarmaParams. Used specifically for Actors using RagDoll physics.
| KSkeleton | Text name of Karma Asset to load from .me file to use to simulate this skeletal mesh. |
Actors simulated using Karma will use the gravity specified by the Physics Volume they are currently in.
Having the player interact with Karma simulated actors is a subtle area. There are three main types on iteraction.
This works at the moment. The default behaviour for each Actor derived from KActor is to have an impulse applied to the point where the shot hit.
Having the player interact directly with other Karma Actors is a little more difficult. Currently the player will just pass through any Karma-simulated Actor. Initially the player will simply be blocked by Actors using Karma, and more complex interaction (see-saws, jumping onto stacks) will be added in the future.
Currently there is no direct support for the user picking up and moving other Karma Actors. However, there are special constaint types that allow a player to pick up and manipulate objects (making stacks etc.), and these could be exposed in the future as needed.
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.
| | Default |
|---|
| KConstraintActor1 | First Actor to connect with this joint. |
| KConstraintActor2 | Other Actor to connect with this joint. Leave blank to connect KConstraintActor1 to world. |
| bKDisableCollision | Disable Karma collision between two Actors joined together. | True |
| KForceThreshold | Force inside constraint at which KForceExceed UnrealScript event is triggered. | 0 |
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.
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.
| | Default |
|---|
| KHalfAngle | Size of cone to limit Actors to. Uses Unreal scale of 65535 = 360 degrees. |
| KStiffness | How 'springy' the limit is when you hit it A larger number makes a hard stop, a small number makes a springy stop. |
| KDamping | How much damping the limit has when you reach it. |
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:
| HT_Normal | Basic hinge. Free to rotate about given axis. |
| HT_Springy | Hinge acts like a spring about its desired angle. |
| HT_Motor | Hinge acts as a motor. |
| HT_Controlled | Hinge acts like a motor, but trying to achive a desired angle. |
The parameters that are used to configure the hinge are given below.
| | Default |
|---|
| KHingeType | | HT_Normal |
| KStiffness | HT_Spring only. | 50 |
| KDamping | HT_Springy only. | 0 |
| KDesiredAngVel | HT_Motor and HT_Controlled only. | 0 |
| KMaxTorque | HT_Motor and HT_Controlled only. | 0 |
| KDesiredAngle | HT_Springy and HT_Controlled only. Angle to try and get achieve, either as a spring or as a motor. | 0 |
| KAltDesiredAngle | Alternative angle to use if KUseAltDesired is True. (65535 = 360 degrees) | 0 |
| KUseAltDesired | Use KAltDesiredAngle instead of KDesiredAngle for desired angle. (65535 = 360 degrees) | False |
| KProportionalGap | HT_Controlled only. | 8200 |
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 behaviours can be achieved.
| ToggleMotor | Trigger will cause the hinge type to change to HT_Motor. Another trigger will toggle it to HT_Controlled, and set KDesiredAngle to its current angle, so it will try to maintain it. |
| ControlMotor | Trigger will turn motor on. Untrigger will turn toggle it to HT_Controlled, and it will try and maintain its current angle. |
| ToggleDesired | Trigger will toggle the hinge between using KDesiredAngle and KAltDesiredAngle. It will use whatever the current KHingeType is to achieve this, so this is only useful with HT_Controlled and HT_Springy. Another trigger and it will use KDesiredAngle again. |
| ControlDesired | Trigger will cause the hinge to use KAltDesiredAngle. Untrigger will cause it to use KDesiredAngle. |
This is a specialised 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.
| | Default |
|---|
| KSteerAngle | Current desired steering angle for this wheel. (65535 = 360 degrees) | 0 |
| KProportionalGap | See KHinge. Used for steering controller. (65535 = 360 degrees) | 8200 |
| KMaxSteerTorque | See KHinge. Used for steering controller. | 1000 |
| KMaxSteerSpeed | See KHinge. Used for steering controller. (65535 = 1 rev/sec) | 2600 |
| bKSteeringLocked | Indicates if wheel can be steered or are locked straight ahead. | True |
| KMotorTorque | Max drive torque applied to achieve KMaxSpeed. See KMaxTorque on KHinge. | 0 |
| KMaxSpeed | Max drive angular velocity to try and achieve. See KDesiredAngVel on KHinge. (65535 = 1 rev/sec) | 655350 |
| KBraking | Amount of braking torque to apply. | 0 |
| KSuspLowLimit | Lower hard stop on suspension. | -1 |
| KSuspHighLimit | Upper hard stop on suspension travel. | 1 |
| KSuspStiffness | Suspension spring stuffness. | 50 |
| KSuspDamping | Suspension damping. | 5 |
| KSuspRef | Equilibrium (unloaded) position of suspension. | 0 |
There are several very useful console commands that are very useful for figuring out what exactly is going on with your simulation:
| kdraw collision | Show all karma collision geometry in green wireframe. |
| kdraw contacts | Show active contacts indicating position, penetration and normal. |
| kdraw joints | Show joints including limits. |
| kdraw triangles | Show all terrain/bsp triangles being considered by Karma collision. |
| kdraw com | Show the centre of mass of Karma-simulated Actors. |
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.
Take a look at the 'Creating Good Simulations With Karma' chapter in the Karma User Guide (page 85) for lots of useful information.
- 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.
- There is no swept check when moving Karma actors. 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.
| Attachment: | Action: | Size: | Date: | Who: | Comment: |
|---|
 KarmaUserGuide.pdf | action | 2213175 | 25 Apr 2002 - 01:21 | KarmaUnrealIntegrationTeam | |
| Userguide1_2.pdf | action | 2213175 | 18 Apr 2002 - 10:15 | KarmaUnrealIntegrationTeam | |
|
|
