Justin Stephens / Physac-MBED

MBED port of the Physacs library

README.md@0:e39efa4f4f58, 20 months ago (annotated)

Committer:
jstephens78
Date:
Tue Nov 29 22:42:42 2022 +0000
Revision:
0:e39efa4f4f58
Child:
1:ebc0214989c0
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jstephens78 0:e39efa4f4f58 1 <img src="https://github.com/victorfisac/Physac/blob/master/icon/physac_256x256.png">
jstephens78 0:e39efa4f4f58 2
jstephens78 0:e39efa4f4f58 3 # Physac
jstephens78 0:e39efa4f4f58 4
jstephens78 0:e39efa4f4f58 5 Physac is a small 2D physics engine written in pure C. The engine uses a fixed time-step thread loop to simluate physics.
jstephens78 0:e39efa4f4f58 6 A physics step contains the following phases: get collision information, apply dynamics, collision solving and position correction. It uses a very simple struct for physic bodies with a position vector to be used in any 3D rendering API.
jstephens78 0:e39efa4f4f58 7
jstephens78 0:e39efa4f4f58 8 The header file includes some tweakable define values to fit the results that the user wants with a minimal bad results. Most of those values are commented with a little explanation about their uses.
jstephens78 0:e39efa4f4f58 9
jstephens78 0:e39efa4f4f58 10 _Note: The example code uses raylib programming library to create the program window and rendering framework._
jstephens78 0:e39efa4f4f58 11
jstephens78 0:e39efa4f4f58 12 Installation
jstephens78 0:e39efa4f4f58 13 -----
jstephens78 0:e39efa4f4f58 14
jstephens78 0:e39efa4f4f58 15 Physac requires raylib. To get it, follow the next steps:
jstephens78 0:e39efa4f4f58 16
jstephens78 0:e39efa4f4f58 17 * Go to [raylib](https://www.github.com/raysan5/raylib) and clone the repository.
jstephens78 0:e39efa4f4f58 18 * Ensure to pull the last changes of 'master' branch.
jstephens78 0:e39efa4f4f58 19 * Use code inside examples header comments to compile and execute.
jstephens78 0:e39efa4f4f58 20
jstephens78 0:e39efa4f4f58 21 Physac API
jstephens78 0:e39efa4f4f58 22 -----
jstephens78 0:e39efa4f4f58 23
jstephens78 0:e39efa4f4f58 24 The PhysicsBody struct contains all dynamics information and collision shape. The user should use the following structure components:
jstephens78 0:e39efa4f4f58 25 ```c
jstephens78 0:e39efa4f4f58 26 typedef struct *PhysicsBody {
jstephens78 0:e39efa4f4f58 27 unsigned int id;
jstephens78 0:e39efa4f4f58 28 bool enabled; // Enabled dynamics state (collisions are calculated anyway)
jstephens78 0:e39efa4f4f58 29 Vector2 position; // Physics body shape pivot
jstephens78 0:e39efa4f4f58 30 Vector2 velocity; // Current linear velocity applied to position
jstephens78 0:e39efa4f4f58 31 Vector2 force; // Current linear force (reset to 0 every step)
jstephens78 0:e39efa4f4f58 32 float angularVelocity; // Current angular velocity applied to orient
jstephens78 0:e39efa4f4f58 33 float torque; // Current angular force (reset to 0 every step)
jstephens78 0:e39efa4f4f58 34 float orient; // Rotation in radians
jstephens78 0:e39efa4f4f58 35 float staticFriction; // Friction when the body has not movement (0 to 1)
jstephens78 0:e39efa4f4f58 36 float dynamicFriction; // Friction when the body has movement (0 to 1)
jstephens78 0:e39efa4f4f58 37 float restitution; // Restitution coefficient of the body (0 to 1)
jstephens78 0:e39efa4f4f58 38 bool useGravity; // Apply gravity force to dynamics
jstephens78 0:e39efa4f4f58 39 bool isGrounded; // Physics grounded on other body state
jstephens78 0:e39efa4f4f58 40 bool freezeOrient; // Physics rotation constraint
jstephens78 0:e39efa4f4f58 41 PhysicsShape shape; // Physics body shape information (type, radius, vertices, normals)
jstephens78 0:e39efa4f4f58 42 } *PhysicsBody;
jstephens78 0:e39efa4f4f58 43 ```
jstephens78 0:e39efa4f4f58 44 The header contains a few customizable define values. I set the values that gived me the best results.
jstephens78 0:e39efa4f4f58 45
jstephens78 0:e39efa4f4f58 46 ```c
jstephens78 0:e39efa4f4f58 47 #define PHYSAC_MAX_BODIES 64
jstephens78 0:e39efa4f4f58 48 #define PHYSAC_MAX_MANIFOLDS 4096
jstephens78 0:e39efa4f4f58 49 #define PHYSAC_MAX_VERTICES 24
jstephens78 0:e39efa4f4f58 50 #define PHYSAC_CIRCLE_VERTICES 24
jstephens78 0:e39efa4f4f58 51
jstephens78 0:e39efa4f4f58 52 #define PHYSAC_COLLISION_ITERATIONS 100
jstephens78 0:e39efa4f4f58 53 #define PHYSAC_PENETRATION_ALLOWANCE 0.05f
jstephens78 0:e39efa4f4f58 54 #define PHYSAC_PENETRATION_CORRECTION 0.4f
jstephens78 0:e39efa4f4f58 55 ```
jstephens78 0:e39efa4f4f58 56
jstephens78 0:e39efa4f4f58 57 Physac contains defines for memory management functions (malloc, free) to bring the user the opportunity to implement its own memory functions:
jstephens78 0:e39efa4f4f58 58
jstephens78 0:e39efa4f4f58 59 ```c
jstephens78 0:e39efa4f4f58 60 #define PHYSAC_MALLOC(size) malloc(size)
jstephens78 0:e39efa4f4f58 61 #define PHYSAC_FREE(ptr) free(ptr)
jstephens78 0:e39efa4f4f58 62 ```
jstephens78 0:e39efa4f4f58 63
jstephens78 0:e39efa4f4f58 64 The Physac API functions availables for the user are the following:
jstephens78 0:e39efa4f4f58 65
jstephens78 0:e39efa4f4f58 66 ```c
jstephens78 0:e39efa4f4f58 67 // Initializes physics values, pointers and creates physics loop thread
jstephens78 0:e39efa4f4f58 68 void InitPhysics(void);
jstephens78 0:e39efa4f4f58 69
jstephens78 0:e39efa4f4f58 70 // Returns true if physics thread is currently enabled
jstephens78 0:e39efa4f4f58 71 bool IsPhysicsEnabled(void);
jstephens78 0:e39efa4f4f58 72
jstephens78 0:e39efa4f4f58 73 // Sets physics global gravity force
jstephens78 0:e39efa4f4f58 74 void SetPhysicsGravity(float x, float y);
jstephens78 0:e39efa4f4f58 75
jstephens78 0:e39efa4f4f58 76 // Creates a new circle physics body with generic parameters
jstephens78 0:e39efa4f4f58 77 PhysicsBody CreatePhysicsBodyCircle(Vector2 pos, float radius, float density);
jstephens78 0:e39efa4f4f58 78
jstephens78 0:e39efa4f4f58 79 // Creates a new rectangle physics body with generic parameters
jstephens78 0:e39efa4f4f58 80 PhysicsBody CreatePhysicsBodyRectangle(Vector2 pos, float width, float height, float density);
jstephens78 0:e39efa4f4f58 81
jstephens78 0:e39efa4f4f58 82 // Creates a new polygon physics body with generic parameters
jstephens78 0:e39efa4f4f58 83 PhysicsBody CreatePhysicsBodyPolygon(Vector2 pos, float radius, int sides, float density);
jstephens78 0:e39efa4f4f58 84
jstephens78 0:e39efa4f4f58 85 // Adds a force to a physics body
jstephens78 0:e39efa4f4f58 86 void PhysicsAddForce(PhysicsBody body, Vector2 force);
jstephens78 0:e39efa4f4f58 87
jstephens78 0:e39efa4f4f58 88 // Adds a angular force to a physics body
jstephens78 0:e39efa4f4f58 89 void PhysicsAddTorque(PhysicsBody body, float amount);
jstephens78 0:e39efa4f4f58 90
jstephens78 0:e39efa4f4f58 91 // Shatters a polygon shape physics body to little physics bodies with explosion force
jstephens78 0:e39efa4f4f58 92 void PhysicsShatter(PhysicsBody body, Vector2 position, float force);
jstephens78 0:e39efa4f4f58 93
jstephens78 0:e39efa4f4f58 94 // Returns the current amount of created physics bodies
jstephens78 0:e39efa4f4f58 95 int GetPhysicsBodiesCount(void);
jstephens78 0:e39efa4f4f58 96
jstephens78 0:e39efa4f4f58 97 // Returns a physics body of the bodies pool at a specific index
jstephens78 0:e39efa4f4f58 98 PhysicsBody GetPhysicsBody(int index);
jstephens78 0:e39efa4f4f58 99
jstephens78 0:e39efa4f4f58 100 // Returns the physics body shape type (PHYSICS_CIRCLE or PHYSICS_POLYGON)
jstephens78 0:e39efa4f4f58 101 int GetPhysicsShapeType(int index);
jstephens78 0:e39efa4f4f58 102
jstephens78 0:e39efa4f4f58 103 // Returns the amount of vertices of a physics body shape
jstephens78 0:e39efa4f4f58 104 int GetPhysicsShapeVerticesCount(int index);
jstephens78 0:e39efa4f4f58 105
jstephens78 0:e39efa4f4f58 106 // Returns transformed position of a body shape (body position + vertex transformed position)
jstephens78 0:e39efa4f4f58 107 Vector2 GetPhysicsShapeVertex(PhysicsBody body, int vertex);
jstephens78 0:e39efa4f4f58 108
jstephens78 0:e39efa4f4f58 109 // Sets physics body shape transform based on radians parameter
jstephens78 0:e39efa4f4f58 110 void SetPhysicsBodyRotation(PhysicsBody body, float radians);
jstephens78 0:e39efa4f4f58 111
jstephens78 0:e39efa4f4f58 112 // Unitializes and destroy a physics body
jstephens78 0:e39efa4f4f58 113 void DestroyPhysicsBody(PhysicsBody body);
jstephens78 0:e39efa4f4f58 114
jstephens78 0:e39efa4f4f58 115 // Unitializes physics pointers and closes physics loop thread
jstephens78 0:e39efa4f4f58 116 void ClosePhysics(void);
jstephens78 0:e39efa4f4f58 117 ```
jstephens78 0:e39efa4f4f58 118 _Note: InitPhysics() needs to be called at program start and ClosePhysics() before the program ends. Closing and initializing Physac during the program flow doesn't affect or produces any error (useful as a 'reset' to destroy any created body by user in runtime)._
jstephens78 0:e39efa4f4f58 119
jstephens78 0:e39efa4f4f58 120 Dependencies
jstephens78 0:e39efa4f4f58 121 -----
jstephens78 0:e39efa4f4f58 122
jstephens78 0:e39efa4f4f58 123 Physac uses the following C libraries for memory management, math operations and some debug features:
jstephens78 0:e39efa4f4f58 124
jstephens78 0:e39efa4f4f58 125 * stdlib.h - Memory allocation [malloc(), free(), srand(), rand()].
jstephens78 0:e39efa4f4f58 126 * stdio.h - Message logging (only if PHYSAC_DEBUG is defined) [printf()].
jstephens78 0:e39efa4f4f58 127 * math.h - Math operations functions [cos(), sin(), fabs(), sqrtf()].
jstephens78 0:e39efa4f4f58 128
jstephens78 0:e39efa4f4f58 129 **It is independent to any graphics engine** and prepared to use any graphics API and use the vertices information (look at examples Drawing logic) to draw lines or shapes in screen. For example, this vertices information can be use in OpenGL API glVertex2f().
jstephens78 0:e39efa4f4f58 130
jstephens78 0:e39efa4f4f58 131 By the way, I use [raylib](http://www.raylib.com) to create the examples. This videogames programming library is used to handle inputs, window management and graphics drawing (using OpenGL API).