Ok so we didn't get a separate forum dedicated to Physics in GG and it is a relatively large topic but I've had a couple of requests so what I aim to do here is explain, briefly, the LUA commands I've added to GG to give some control over the Physics engine and more importantly how to use the phylib.lua to use them productively.

So first some of the new functions (don't worry if the names don't mean anything at the moment):
ConstrainObjMotion( objID, x, y, z )
ConstrainObjRotation( objID, x, y, z )
These two commands tell the Physics engine to only allow a physics entity to move or rotate in specific axis.
Setting x, y or z = 0 means no motion on that axis, 1 means motion allowed.
An example of use would be something like this:


For the following commands I've omitted the parameters because the physlib module provides a set of simpler functions to use them which I will describe below. There is no guarantee that the parameter lists will not change in future so the safest way to use them will be via the library calls. (all will become clear later)

CreateSingleHinge( … ) This command creates a physics 'hinge' between the world and a specified object.
CreateDoubleHinge( … ) This command creates a physics 'hinge' between two specified objects.
CreateSingleJoint( … ) This command creates a physics 'joint' between the world and a specified object.
CreateDoubleJoint( … ) This command creates a physics 'joint' between two specified objects.

RemoveObjectConstraints( objID )
This command removes any constraints applied to an object, I'll show the usage of this in a worked example later.

SetObjectDamping( objID, damping, angle )
This command applies a damping factor to an object, basically this makes it resist motion. Again I'll probably explain this in more detail later.

PushObject( objID, vx, vy, vz, rx, ry, rz )
Simple sounding command but tricky to describe exactly what it does, it applies an instantaneous force to an object in the direction specified by the v parameters (v for vector) with a radial offset specified by the r parameters. Again I'll describe this in more detail later.

(this is just a few of the new commands to get us started!)

Now introduction to the physlib library and how to make it accessible from within your scripts:

As you are probably aware GG uses the Bullet Engine for Physics, badly it has to be said and nowhere near as well as it could, and strangely enough the documentation on the Bullet engine is pretty sparse so I set out to try and provide some, albeit limited, Lua control over the Physics.
Now some of the things I've added are more aimed at modellers, e.g. setting collision mode to 2 or 3 on an entity in the fpe file will cause GG to create a spherical or cylindrical physics shape (balls and barrels iow ) which in turn means they will react more realistically in game (assuming they are in fact spherical or cylindrical in shape of course!) but most are aimed at scripters who want to add subtle touches like doors that the player can push open or signs swinging in the wind etc.
So to this end I've created physlib.lua which is a Lua library module to complement utillib.lua (which contains a bunch of utility functions) and quatlib.lua (which provides quaternion functions for rotating entities smoothly).

The magical incantation to include the functions provided by the library in your own scripts is simply:


Assuming you have copied my usage of P for the library any functions in the library are invoked by P.<function name>( parameters ) so for example P.GetEntityDimensions( e ).

Next post I'll start describing the physlib functions and how to use them. Stay tuned!

So the first function I'm going to describe basically provides the dimensions of a specified object, it does this by using some other lower level functions under the covers and a bit of math. It is also an example of a memoizing function, basically it remembers the result of the call for a particular object and if you call it again for the same object can return the values much faster.

This function returns a list of the form { w, h, l, m, cx, cy, cx, ... } ( the ... refers to some other values that for now aren't important)
where:
w = width of the object, i.e. the "x" dimension
h = height of the object, i.e. the "y" dimension
l = length of the object, i.e. the "z" dimension
m = mass of the object (internally GG has a rather strange mass calculation which this mimics)
cx, cy, cz = the 'centre' offsets of the object, i.e. where the centre of the object is relative to its origin.

If you want to see how this is used 'in anger' take a look in the pickuppables.lua script!

This function comes in an 'objectID' flavour and an 'entityID' flavour, example:


Next up is a function that you will also find in the utillib library but with a subtle difference: ObjectPlayerLookingAt( distance, force )
This function is an example of a function with an optional parameter, i.e. the 'force' parameter which you only need to include if you want to apply a force to the object. Many of the functions in these libraries are like this.
The subtle difference is that whereas the utillib version returns any object that the player is looking at the physlib version only returns 'physics' objects.
Example of usage:


To be continued ...

For the next couple of functions I'm going to give a worked example of use, i.e. we will end up with a working script that you can play with.

Hinges! What are they? Well simply put a hinge is an axis constraint, either on a single entity or between two separate entities.

For your very first example create a script, lets call it hinge.lua, which should look like this:


Now attach the script to an active entity and make sure it is set physics 'on', for example a crate, set the 'strength' of the entity to say 200 and raise it off the ground to say head height.
Place the start marker and give yourself a weapon.

You should end up with something like this:



Tomorrow I will dissect this enormous script and describe what is going on, then we can move on to something more fun, i.e. I'll show you how to string up a punchbag on a chain.

In the meantime those of a more adventurous spirit can go explore the rest of physlib.lua for themselves!

Right, so what does the script do exactly?

cons = P.AddEntitySingleHinge( e, "TopCentreW" )

This function is the easiest to use as it hides everything, pretty much, under the covers and only exposes what you need to get the job done (which is what all the best software should do!).
In the library there is a list of named hinges, you specify the hinge by name and the library function does the hard work of creating the appropriate gobbledy-gook to pass into GG.
The list at present contains the following choices:
'TopLeft', 'TopRight', 'TopFront', 'TopBack', 'TopCentreW', 'TopCentreL',
'BottomLeft', 'BottomRight', 'BottomFront', 'BottomBack', 'BottomCentreW', 'BottomCentreL',
'LeftBack', 'LeftFront', 'LeftCentre', 'FrontCentre', 'BackCentre',
'RightBack', 'RightFront', 'RightCentre',
'CentreVertical', 'CentreWidth', 'CentreLength', 'CentreFront', 'CentreBack'


Phew! The first part of the name defines where on the entity the hinge is attached and the rest of the name defines the axis, so for example 'TopLeft' means that the hinge lies along the top left hand edge of the model.

The best way to see what they all do is to simply try them out so to make that even easier lets have a simple script to enable us to do that:


Simply attach that script to your entity, clone it a bunch of times then name the entities with the name of a hinge from the list above to see what each one does.

The next function I'll briefly describe is from the first script again:
P.RemoveEntityConstraintsIfDead( e )

This one does exactly what it's name suggests, it checks to see if the entities health is zero and if so removes any constraints that have been set for that entity, as soon as the constraint have been removed then normal Physics take over and the entity will fall due to gravity etc.

(Note that the AddEntitySingleHinge function returns a value (I've assigned it to 'cons' in the first script), this is an identifier of the constraint in the Bullet Engine that can then be used by other functions later to alter the constraint in some way. For example if you set a hinge constraint with angular limits then later you can alter those limits by passing the identifier to specify which constraint you are modifying, this is me future proofing btw I haven't added support for this fully yet but when I do you will find the functions to do it in the library.)

The next function to cover is easier to explain because it basically works in exactly the same way as the hinge but the result is different:
P.AddEntitySingleJoint( e, jointName, spacing )
The difference between a hinge and a joint is simply that the hinge constrains motion around a specified axis, i.e. like a door or wheel motion, whereas a joint constrains to a single point with rotation in all axis, i.e. like a hanging light.
This function uses the same name list as the hinge to define the location of the constraint.
Note the optional 'spacing' parameter, this can also be specified for hinges and I'll explain this in more detail later.
In fact the optional parameter list for single hinges is:
swingAng : defines the angle through which the hinge can operate
offset : defines the centre of the swing angle as a percentage
spacing : adds an offset to the hinge location, this is a list of the form { w, h, l } where:
w = width (or x offset)
h = height (or y offset)
l = length (or z offset)
Now you may be wondering why I use w, h & l if I really mean x, y & z, well it's because x, y, z is used to define a position in world space width, height and length are dimensions relative to the model origin.

I'll explain these optional parameters when we use them in anger.

Next post I'll introduce the 'Double' versions of these functions and we'll start to put together a fun example.

Ok, so we've seen the functions which set a constraint between the 'world' and an entity, we also require functions to add constraints between two entities:

P.AddEntityDoubleHinge( e1, e2, hingeName1, hingeName2, spacing, noCols )
P.AddEntityDoubleJoint( e1, e2, jointNameA, jointNameB, spacing, noCols )

Notice that these functions work in exactly the same way as the single versions except that you specify two entities and the constraint acts solely between them.
The spacing and noCols parameters are optional and I'll explain them later.

So lets put these to use and create a chain using the attached script.

This script (hinge_chain_alternating.lua) works on three named entities:

'ChainStart' : The entity that will be anchored to the world and which the rest of the chain will hang from.
'ChainLink' : One or more links in the chain, the script will attach these together with hinge constraints in alternating axis.
'ChainEnd' : Whatever you want to hang on the end of the chain.

Whilst you all stare in befuddlement at this script, I'm going to fiddle around with some models we need to make use of this.

Onward and upward!

Attached you should find a zip file with 4 entities, basically they are IIRC all from GraPhiX and all I've done is fiddled with them a bit so we can make them work better in a Physics setting.

To make up our little demo we need to do the following:

1) Place the stand down, select properties and set IsImmobile : Yes. This forces the physics shape to be the actual shape of the stand, we need to do this because the bag will hang uinder it and we want the two to be able to interact.

2) Place the hook on the stand, locate it using the bolt on top of the stand. Set it's properties to:
Name : ChainStart
Static Mode : No
IsImmobile : Yes
Physics On : Yes
Always Active : Yes
Attach the script from the previous post.

3) Place the chain link and set its properties to:
Name : ChainLink
Static Mode : No
IsImmobile : No
Physics On : Yes
Always Active : Yes
Attach the script from the previous post.

Copy the chain link so you have three of them and place them under the hook.

4) Place the bag, set it's properties:
Name : ChainEnd
Static Mode : No
IsImmobile : No
Physics On : Yes
Always Active : Yes
Physics Weight : 3 (this is important! To see why after you have this all working change it and see what happens!)
Attach the script from the previous post.

Now in theory when you hit the rocket you will see something like this:


Notice that even with a simple weapon, in this case a thrown stone, the Physics reaction is extreme to say the least. This is partly becasue the force applied by the 'stone' weapon is way too high and partly because GG's mass calculations are rather weird. On another thread where I have a video where I am pushing the bag the force being use is the minimum, i.e. '1'. This is one area where more improvements are needed in the engine to cap the forces to within the limits of the Bullet engine to make Physics interractions more realistic.

Having said all that, if you play around with the settings and use the SetEntityDamping function with appropriate values you can tame GG to give resonable results.

Unpack this into your gamecore/guns folder, drop in a start marke and select 'unarmed' for the weapon.

Also replace the chain link with the attached model file and delete the .dbo version (I've just centred the mesh as it seems to work better than the previous one for some reason).

AWESOME

Not sure if this all works in the non-Beta build (PP or whatever it's called these days), has anyone tried it?

I loaded up the latest Public Preview, but I didn't see physlib in the script folder and I couldn't get it to work... I guess it's still in beta only.

I do like your explanations though... I think I have a better general idea of physlib.

So do you have the pickuppables with push/pull/throw?

It looks like my scriptbank has pickuppable.lua, as well as quatlib and utillib.

I could pick up a box and rotate it, but I could not figure out how to push it (other then walk into it).

Ahh, in that case the physics stuff hasn't made it into the PP yet, I presume Lee is planning on releasing it soon but is probably waiting for some of the performance enhancements to be fully tested or something.

Appreciate your tutorial. Thank you.

I have the beta version 2018-06-16. However, the physlib.lua was uploaded in a couple of versions back. The date for this file is 2018-06-02, so apparently, it was only a part of a newer beta version which is not yet PP. The PP should be released anytime now. It is still being tested by beta testers.

I'll wait for the PP release before going any further then, but I'm happy to answer any questions on what I've posted so far.

Awesome tutorial AmenMoses. Thank you.

This will take some time for me to unpack, you've also probably given me another chapter in my book to write so I should probably thank you for that

Only one chapter?

I downloaded the latest Public Preview (18 June 2018) and it looks like we now have physlib... I tried your example of the red basket with the hinge script and it worked exactly as you show it.

Thanks AmenMoses... I'm looking forward to learning more.

Ok so it's time for something simple.

First place an object on the map that you want to push around, like for example the Cinderblocks stack. Make it Static Mode = No (i.e. dynamic) and set the weight and friction to 50.

Now hit test game and try to push it around by walking into it. Not very convincing is it?

So now attach the push.lua script to a crate or similar and make it always active and retest.

I've used one of the new physics commands here, i.e. PhysicsRayCast, but rather than use it to detect an object with a ray I've used it to apply a push force to any physics object just in front of the player.

I'm going to build on this in the next post and use it to demonstrate the constraint commands.

The two commands ConstrainObjMotion and ConstrainObjRotation compliment each other.

Basically they take an object Id and three 'constraint' parameters, each constraint parameter specifies an axis i.e. x, y, z. If the parameter value is 0 then no physics will apply on that axis, 1 and physics does apply.

So as an example:

ConstrainObjMotion( ObjId, 1, 0, 1 )
ConstrainObjRotation( ObjId, 0, 1, 0 )

This combination will constrain motion to x and z axis only and rotation to y axis only, iow it will smooth our pushed objects motion considerably.

Bearing in mind that the object Id is given by g_Entity[ e ].obj I'll leave it as an exercise for the reader to write this script, hint; the constraint commands only need to be applied once in the _init function.

Attach the script to the 'pushable object' from the previous post and see what the effect is. Try raising the object slightly above the terrain to see how that affects it, also play with the '50' value and the '500' value in the push script to see how they affect the result.

Finally, try different combinations of constraints to see how they affect the result, e.g. try constraining the object in x or z axis and try 0,0,0 for the rotation constraints.

Have fun!

Next time I'll cover damping.

If you managed to write your own working constraint script, well done. If not I've attached here an example of what is should have looked like.

I've also tweaked the push script a bit in an attempt to make the 'pushing' a bit more realistic, still not perfect but you will find that with physics stuff it will never be perfect, when trying to fake reality (just like lighting and sound) all you can ever do is get 'close enough'.

Here is a short video of these scripts in action:


Things to note:
1) By altering the players maximum walk speed whilst 'pushing' you can somewhat avoid the 'jerkyness' which is caused by the players own 'physics' interaction getting in the mix. The player 'shape' is a capsule which is curved, when the physics engine attempts to mimic the effect of a curved surface pushing against a mesh it does the best it can but can never be as smooth as the 'push' we are giving which is at a specific point, in a very specific direction with a constant force.

2) The top stack in the video is a simple dynamic object with no script or anything special, we are pushing the bottom stack and as you can see the top stack reacts in a reasonably realistic fashion. This is because the movement of the top stack is completely controlled by the Bullet engine. Even though GG does not handle friction and mass correctly (it is *not* designed as a simulator, it's a game engine!) this part of the physics is quite reliable.

3) All rotation has been eliminated! The stacks can be moved around the map in any horizontal direction but the height and rotation is locked, this means that you can control the game mechanics in such a way that the player can't force objects into places or orientations that they shouldn't be in. (very important if you carefully design a puzzle for the player to solve in one area of the level and the player goes and shoves part of the puzzle into different area and can't complete the puzzle!)

4) With the 'pushable' entity raised above the terrain slightly we no longer have a 'friction' component at play so the motion is smoother but now the object doesn't behave the way the player may expect. Visually it is a large pile of heavy things so we would not expect it to carry on moving as it if it were on ice.

This last point is what I'll tackle next, basically I've hard wired into GG a modest 'damping' factor but in reality one size does not fit all when it comes to damping so in order to be able to 'tweak' the behaviour of a physics object to match it's appearance there is a new command: SetObjectDamping which enables objects to be given custom damping values. Later today I'll add this into our example.

This all might seem a little simplistic so far but I'm covering the basics in as much detail as I can because it is the small simple stuff which you really need to get right in order to give the illusion of 'real' physics in your games. Big showy stuff might look impressive the first time you see it but soon become passe, but the small stuff like a door that pushs open realistically, a ball that rolls convincingly or a window shutter blowing shut in the 'wind' will help to draw the player into your make believe reality.

Right so a brief explanation of what 'damping' gives us, IRL objects don't carry on moving when you stop pushing them for several reasons, the most obvious is friction. Depending on what the object is and what it is sitting on there will be a friction factor between them that fights against any movement, in addition air itself offers resistance (water even more so).

For friction against the surface the main force affecting the object is gravity, the more massive the object being moved the more friction will be generated, for air/water resistance otoh it is the shape of the object that is more important, a beach ball for example is low in mass but has a large volume meaning a large surface area. It may seem obvious to the reader that a beach ball will react in a completely different way to a solid metal ball of the same size but inside GG all it has is a mesh, there is no real modelling of volume versus mass (in fact the mass calculation pretty much treats every object as a solid of the same density) and no attempt to take into account what an object may be made of (i.e. IRL a wooden box made of Oak will behave differently from a metal box made of steel which in turn will behave differently from one made of aluminium).

So, given the limitations of the game engine and the fact that the models themselves do not give us anything to distinguish them apart, how do we 'cheat' in order to get some sort of realistic behaviour?

The simplest way is to add in a damping factor, simply put this is a fake amount of resistance to movement that is assigned to an object to mimic the real life forces that would normally apply, so in our example we have a stack of bricks and we intuitively know that if we tried to push it, it will resist that push and also when we stop pushing it will quickly stop moving. So we need a large damping factor in this case.

The command we use is:
SetObjectDamping( obj, A, B )

Where A is the resistance to movement and B is the resistance to turning.

In the constrainxy_norotate script from the previous post add the following line to the _init function after the constraints part:

SetObjectDamping( obj, 0.4, 0 )

If you have changed the constraints to allow rotation then change the rotational factor to '0.9' to see how that affects things (with 0 you probably found the object spinning around like mad )

You can change the object damping factors for any physics object on the fly, for example if you detect that the object has been pushed onto an icy surface you could lower the damping factors to allow the object to slide more, when the object has been moved to the location you want it to stay at either change the constraints such that all further movement is disallowed or increase the damping to maximum.

The value range is 0 to 1 btw, 0 give no damping so mimics behaviour in a zero gravity vacuum, 1 is maximum damping which would be like being in Jupiter's ocean.

Try playing around with the damping factor values and the various values in the push script to see if you can
arrive at a realistic behaviour.

I think next up I'm going to cover spherical and cylindrical physics shapes. Maybe now is the appropriate time to create a demo involving soccer balls?

Wow,a lot for me to take in but what a great thread.Hats of to you sir

Dave

Oh dear, it looks like my changes to the collisionmode settings didn't get pushed or merged or whatever, I'll push them later on.

Hmmm, I'll have a rethink to come up with something else to demo, maybe I'll attempt to introduce the collision detection commands I added, although that requires more in the way of coding at the moment and I'll need to think up a sensible example to use them with.

Anyway, for now experiment with the stuff I have demonstrated so far and see if you can come up with some cool examples of your own.

This is So Great!
Thank you SO Much AmenMoses!
This is just what I need.

Time for a bit more fun:



For this little bit of fun I needed a wheel entity with a cylinder collision shape.

Luckily in the scenery folder I found just the thing, it needed a bit of fettling so I popped it into a modelling app and rotated 90 degrees so it is 'flat' (the cylinder collision mode needs this) and also translated the model so the origin point is dead centre. Next I copied the fpe from the base model and edited it.

Next up for the 'body' part I simply scaled up a box slightly.

Make all entities active, physics on and make sure 'isimmobile=no'.

Attach the scripts and position the entities in roughly the right places (like in the attached image) then name the appropriate wheels 'frontL', 'frontR', 'rearL' & 'rearR'. This allows the script to apply the constraints in the right place.

Drop the wheel parts into the scenery folder.

Note that in the previous example I used the CreateDoubleHinge command directly rather than use the physlib functions, this is because I'm placing the constraints very accurately rather than as a named shortcut as we did before.

So to explain how this is accomplished I'll take one example:

CreateDoubleHinge( g_body_object, whObj, 26, -18, 35, 0, 0, 0, 1, 2, 1 )


Firstly note that this command is only executed once, from then on the constraint will be permanent unless you explicitly remove it later on.

The first two values passed in are the object Id of the box and the wheel (this example is for the 'frontR' wheel).

The next three values are the offset location on the first object where the constraint will be created, in this case 26 units to the right of the objects centre, -18 units below the centre and 35 units in front of centre. Or roughly where you would expect the end of the axle to be. I worked this out by trial and error btw.

The next three are the offset location on the second object, the wheel itself which is directly in the centre of the object.

The next two values are harder to explain but basically map within the engine to an axis of the object, so '1' is specifying the 'x' axis of the box and '2' is the 'y' axis of the wheel, if you recall I layed the wheel flat so it's rotational axis is up through the centre or 'y'.

The last value passed is simply telling the engine whether to calculate collisions between the objects involved in the constraint, 0 means yes and 1 means no. In most case you will probably want to say no as otherwise if the collision shapes of the objects intersect at any point the Bullet engine will go nuts trying to push them apart and things will quickly get very messy. (try changing them to '0' and see what happens!).

So now you know what the parameters mean.

A great example of how the physics is working in real time. Notice that the body goes down the hill at a faster and faster rate until it hits the water and it slows down to a standstill. Just like it would in real life.

Can't claim any credit for that, it's just the Bullet engine doing it's stuff, normally in spite of GG trying to get in the way.

All I'm attempting to do with my engine changes and libraries is to expose the functionality of the innards of GG to allow the user to use them.

Forgot to mention above that if you change the fpe file for an entity to set the collisionmode to 2 (for a sphere) or 3 (for a cylinder) this will tell GG to create the collision shape appropriately. After doing this the Bullet physics engine will then treat the entity as either a sphere or a cylinder regardless of what the visual shape 'looks' like on the screen.

So if you get weird motion effects, like a box behaving like a ball, then check the fpe!

very nice

wouldn't this make more sense the other way around? 0 normally means false or 'no'

Well it's really an 'ignore' collisions setting inside the engine, maybe my explanation was a bit confusing.

I could even have used 'yes' and 'no' I suppose, hindsight is 20:20 and al that.