<!DOCTYPE html>
This section records information for easy reference.
The unit system used throughout is SI (Système International d'Unités). In addition to the basic units, several derived units are also used. For each unit, Tab: ToU lists the symbol, a description and the SI name.
| Symbol | Description | SI Name |
|---|---|---|
| J | energy | joule |
| kg | mass | kilogram |
| m | length | metre |
| N | force | newton |
| rad | angle | radian |
| s | time | second |
The symbols used in this document are summarized in Tab: ToS along with their units. Throughout the document, symbols in bold will represent vectors, and scalars otherwise. The symbols are listed in alphabetical order. For vector quantities, the units shown are for each component of the vector.
| Symbol | Description | Units |
|---|---|---|
| a | Acceleration | m/s2 |
| a(t) | Linear Acceleration | m/s2 |
| ai | The I-Th Body's Acceleration | m/s2 |
| CR | Coefficient of restitution | -- |
| F | Force | N |
| F1 | Force exerted by the first body (on another body) | N |
| F2 | Force exerted by the second body (on another body) | N |
| Fi | Force Applied to the I-Th Body at Time T | N |
| G | Gravitational constant | m3/(kg⋅s2) |
| g | Gravitational acceleration | m/s2 |
| h | Height | m |
| I | Moment of inertia | kg⋅m2 |
| IA | Moment of Inertia Of Rigid Body A | kg⋅m2 |
| IB | Moment of Inertia Of Rigid Body B | kg⋅m2 |
| J | Impulse (vector) | N⋅s |
| j | Impulse (scalar) | N⋅s |
| KE | Kinetic energy | J |
| L | Length | m |
| M | Total Mass of the Rigid Body | kg |
| m | Mass | kg |
| m1 | Mass of the first body | kg |
| m2 | Mass of the second body | kg |
| mA | Mass Of Rigid Body A | kg |
| mB | Mass Of Rigid Body B | kg |
| mj | Mass Of the J-Th Particle | kg |
| n | Collision Normal Vector | m |
| PE | Potential energy | J |
| p | Position | m |
| pCM | Center of Mass | m |
| pj | Position Vector of the J-Th Particle | m |
| rj | Distance Between the J-Th Particle and the Axis of Rotation | m |
| r | Displacement | m |
| r(t) | Linear Displacement | m |
| rOB | Displacement vector between the origin and point B | m |
| r̂ | Displacement unit vector | m |
| t | Time | s |
| tc | Denotes the time at collision | s |
| v | Velocity | m/s |
| Δv | Change in velocity | m/s |
| v(t) | Linear Velocity | m/s |
| vAP | Velocity Of the Point of Collision P in Body A | m/s |
| vBP | Velocity Of the Point of Collision P in Body B | m/s |
| v1 | Velocity Of the First Body | m/s |
| v2 | Velocity Of the Second Body | m/s |
| vA | Velocity At Point A | m/s |
| vB | Velocity At Point B | m/s |
| vfAB | Final Relative Velocity Between Rigid Bodies of A and B | m/s |
| vi | Velocity Of the I-Th Body's Velocity | m/s |
| viAB | Initial Relative Velocity Between Rigid Bodies of A and B | m/s |
| vO | Velocity At Point Origin | m/s |
| ||n|| | Length of the Normal Vector | m |
| ||r|| | Euclidean norm of the displacement | m |
| ||rAP*n|| | Length of the Perpendicular Vector To the Contact Displacement Vector of Rigid Body A | m |
| ||rBP*n|| | Length of the Perpendicular Vector To the Contact Displacement Vector of Rigid Body B | m |
| ||r||2 | Squared distance | m2 |
| α | Angular Acceleration | rad/s2 |
| θ | Angular Displacement | rad |
| τ | Torque | N⋅m |
| τi | Torque applied to the i-th body | N⋅m |
| ω | Angular Velocity | rad/s |
| ϕ | Orientation | rad |
| Abbreviation | Full Form |
|---|---|
| 2D | Two-Dimensional |
| 3D | Three-Dimensional |
| A | Assumption |
| CM | Centre of Mass |
| Chipmunk2D | Chipmunk2D game physics library |
| DD | Data Definition |
| GD | General Definition |
| GS | Goal Statement |
| IM | Instance Model |
| LC | Likely Change |
| ODE | Ordinary Differential Equation |
| R | Requirement |
| SRS | Software Requirements Specification |
| TM | Theoretical Model |
| UC | Unlikely Change |
| Uncert. | Typical Uncertainty |
Due to the rising cost of developing video games, developers are looking for ways to save time and money for their projects. Using an open source physics library that is reliable and free will cut down development costs and lead to better quality products.
The following section provides an overview of the Software Requirements Specification (SRS) for Chipmunk2D. This section explains the purpose of this document, the scope of the system, the characteristics of the intended reader, and the organization of the document.
This document describes the modeling of an open source 2D rigid body physics library used for games. The theoretical models and goal statements used in Chipmunk2D are provided. This document is intended to be used as a reference to provide all necessary information to understand and verify the model.
This document will be used as a starting point for subsequent development phases, including writing the design specification and the software verification and validation plan. The design document will show how the requirements are to be realized, including decisions on the numerical algorithms and programming environment. The verification and validation plan will show the steps that will be used to increase confidence in the software documentation and the implementation. Although the SRS fits in a series of documents that follow the so-called waterfall model, the actual development process is not constrained in any way. Even when the waterfall model is not followed, as Parnas and Clements point out parnasClements1986, the most logical way to present the documentation is still to "fake" a rational design process.
The scope of the requirements includes the physical simulation of 2D rigid bodies acted on by forces.
Reviewers of this documentation should have an understanding of rigid body dynamics and high school calculus. The users of Chipmunk2D can have a lower level of expertise, as explained in Section: User Characteristics.
The organization of this document follows the template for an SRS for scientific computing software proposed by dParnas1972 and parnasClements1984. The presentation follows the standard pattern of presenting goals, theories, definitions, and assumptions. For readers that would like a more bottom up approach, they can start reading the instance models in Section: Instance Models and trace back to find any additional information they require.
The goal statements (Section: Goal Statements) are refined to the theoretical models and the theoretical models (Section: Theoretical Models) to the instance models (Section: Instance Models).
This section provides general information about the system. It identifies the interfaces between the system and its environment, describes the user characteristics, and lists the system constraints.
Fig:sysCtxDiag shows the system context. A circle represents an external entity outside the software, the user in this case. A rectangle represents the software system itself (Chipmunk2D). Arrows are used to show the data flow between the system and its environment.
The interaction between the product and the user is through an application programming interface. The responsibilities of the user and the system are as follows:
The end user of Chipmunk2D should have an understanding of first year programming concepts and an understanding of high school physics.
There are no system constraints.
This section first presents the problem description, which gives a high-level view of the problem to be solved. This is followed by the solution characteristics specification, which presents the assumptions, theories, and definitions that are used.
A system is needed to create a simple, lightweight, fast, and portable 2D rigid body physics library, which will allow for more accessible game development and the production of higher quality products. Creating a gaming physics library is a difficult task. Games need physics libraries that simulate objects acting under various physical conditions, while simultaneously being fast and efficient enough to work in soft real-time during the game. Developing a physics library from scratch takes a long period of time and is very costly, presenting barriers of entry which make it difficult for game developers to include physics in their products. There are a few free, open source and high quality physics libraries available to be used for consumer products (Section: Off-The-Shelf Solutions).
This subsection provides a list of terms that are used in the subsequent sections and their meaning, with the purpose of reducing ambiguity and making it easier to correctly understand the requirements.
Given the kinematic properties, and forces including any (collision forces) applied on a set of rigid bodies, the goal statements are:
The instance models that govern Chipmunk2D are presented in Section: Instance Models. The information to understand the meaning of the instance models and their derivation is also presented, so that the instance models can be verified.
This section simplifies the original problem and helps in developing the theoretical models by filling in the missing information for the physical system. The assumptions refine the scope by providing more detail.
This section focuses on the general equations and laws that Chipmunk2D is based on.
| Refname | TM:NewtonSecLawMot |
|---|---|
| Label | Newton's second law of motion |
| Equation | F = m a |
| Description | |
| Notes | The net force F (N) on a body is proportional to the acceleration a (m/s2) of the body, where m (kg) denotes the mass of the body as the constant of proportionality. |
| Source | -- |
| RefBy |
| Refname | TM:NewtonThirdLawMot |
|---|---|
| Label | Newton's third law of motion |
| Equation | F1 = −F2 |
| Description | |
| Notes | Every action has an equal and opposite reaction. In other words, the force F1 (N) exerted on the second rigid body by the first is equal in magnitude and in the opposite direction to the force F2 (N) exerted on the first rigid body by the second. |
| Source | -- |
| RefBy |
| Refname | TM:UniversalGravLaw |
|---|---|
| Label | Newton's law of universal gravitation |
| Equation | F = G m1 m2||r||2 r̂ = G m1 m2||r||2 r||r|| |
| Description | |
| Notes | Two rigid bodies in the universe attract each other with a force F (N) that is directly proportional to the product of their masses, m1 and m2 (kg), and inversely proportional to the squared distance ||r||2 (m2) between them. The vector r (m) is the displacement between the centres of the rigid bodies and ||r|| (m) represents the Euclidean norm of the displacement, or absolute distance between the two. r̂ denotes the displacement unit vector, equivalent to the displacement divided by the Euclidean norm of the displacement, as shown above. Finally, G is the gravitational constant (6.673 * 10E-11) (m3/(kg⋅s2)). |
| Source | -- |
| RefBy |
| Refname | TM:ChaslesThm |
|---|---|
| Label | Chasles' theorem |
| Equation | vB = vO&plusω⨯rOB |
| Description | |
| Notes | The linear velocity vB (m/s) of any point B in a rigid body A: objectTy is the sum of the linear velocity vO (m/s) of the rigid body at the origin (axis of rotation) and the resultant vector from the cross product of the rigid body's angular velocity ω (rad/s) and the displacement vector between the origin and point B, rOB (m). |
| Source | -- |
| RefBy |
| Refname | TM:NewtonSecLawRotMot |
|---|---|
| Label | Newton's second law for rotational motion |
| Equation | τ = I α |
| Description | |
| Notes | The net torque τ (N⋅m) on a rigid body is proportional to its angular acceleration α (rad/s2). Here, I (kg⋅m2) denotes the moment of inertia of the rigid body. We also assume that all rigid bodies involved are two-dimensional A: objectDimension. |
| Source | -- |
| RefBy |
There are no general definitions.
This section collects and defines all the data needed to build the instance models.
| Refname | DD:ctrOfMass |
|---|---|
| Label | Center of Mass |
| Symbol | pCM |
| Units | m |
| Equation | pCM = ∑mj pjM |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:linDisp |
|---|---|
| Label | Linear Displacement |
| Symbol | r(t) |
| Units | m |
| Equation | r(t) = dp(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:linVel |
|---|---|
| Label | Linear Velocity |
| Symbol | v(t) |
| Units | m/s |
| Equation | v(t) = dr(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:linAcc |
|---|---|
| Label | Linear Acceleration |
| Symbol | a(t) |
| Units | m/s2 |
| Equation | a(t) = dv(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:angDisp |
|---|---|
| Label | Angular Displacement |
| Symbol | θ |
| Units | rad |
| Equation | θ = dϕ(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:angVel |
|---|---|
| Label | Angular Velocity |
| Symbol | ω |
| Units | rad/s |
| Equation | ω = dθ(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:angAccel |
|---|---|
| Label | Angular Acceleration |
| Symbol | α |
| Units | rad/s2 |
| Equation | α = dω(t) dt |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:impulse |
|---|---|
| Label | Impulse (scalar) |
| Symbol | j |
| Units | N⋅s |
| Equation | j = −(1&plusCR) viAB⋅n( 1mA &plus1mB ) ||n||2&plus||rAP*n||2IA &plus||rBP*n||2IB |
| Description | |
| Notes | |
| Source | -- |
| RefBy |
| Refname | DD:chalses |
|---|---|
| Label | Velocity At Point B |
| Symbol | vB |
| Units | m/s |
| Equation | vB = vO&plusω⨯rOB |
| Description | |
| Notes | The linear velocity vB (m/s) of any point B in a rigid body A: objectTy is the sum of the linear velocity vO (m/s) of the rigid body at the origin (axis of rotation) and the resultant vector from the cross product of the rigid body's angular velocity ω (rad/s) and the displacement vector between the origin and point B, rOB (m). |
| Source | -- |
| RefBy |
| Refname | DD:torque |
|---|---|
| Label | Torque |
| Symbol | τ |
| Units | N⋅m |
| Equation | τ = r⨯F |
| Description | |
| Notes | The torque on a body measures the the tendency of a force to rotate the body around an axis or pivot. |
| Source | -- |
| RefBy |
| Refname | DD:kEnergy |
|---|---|
| Label | Kinetic energy |
| Symbol | KE |
| Units | J |
| Equation | KE = m v22 |
| Description | |
| Notes | The kinetic energy of an object is the energy it possess due to its motion. |
| Source | -- |
| RefBy |
| Refname | DD:coeffRestitution |
|---|---|
| Label | Coefficient of restitution |
| Symbol | CR |
| Units | Unitless |
| Equation | CR = −( vfAB⋅nviAB⋅n ) |
| Description | |
| Notes | The coefficient of restitution CR is a unitless, dimensionless quantity that determines the elasticity of a collision between two rigid bodies. CR = 1 results in an elastic collision, while CR < 1 results in an inelastic collision, and CR = 0 results in a totally inelastic collision. |
| Source | -- |
| RefBy |
| Refname | DD:reVeInColl |
|---|---|
| Label | Initial Relative Velocity Between Rigid Bodies of A and B |
| Symbol | viAB |
| Units | m/s |
| Equation | viAB = vAP−vBP |
| Description | |
| Notes | In a collision, the velocity of a rigid body A: objectTy A colliding with another rigid body B relative to that body viAB is the difference between the velocities of A and B at point P. |
| Source | -- |
| RefBy |
| Refname | DD:impulseV |
|---|---|
| Label | Impulse (vector) |
| Symbol | J |
| Units | N⋅s |
| Equation | J = m Δv |
| Description | |
| Notes | An impulse (vector) J occurs when a force F acts over a body over an interval of time. |
| Source | -- |
| RefBy |
Newton's second law of motion states:
Rearranging :
Integrating the right hand side :
| Refname | DD:potEnergy |
|---|---|
| Label | Potential energy |
| Symbol | PE |
| Units | J |
| Equation | PE = m g h |
| Description | |
| Notes | The potential energy of an object is the energy held by an object because of its position to other objects. |
| Source | -- |
| RefBy |
| Refname | DD:momentOfInertia |
|---|---|
| Label | Moment of inertia |
| Symbol | I |
| Units | kg⋅m2 |
| Equation | I = ∑mj rj2 |
| Description | |
| Notes | The moment of inertia I of a body measures how much torque is needed for the body to achieve angular acceleration about the axis of rotation. |
| Source | -- |
| RefBy |
This section transforms the problem defined in Section: Problem Description into one which is expressed in mathematical terms. It uses concrete symbols defined in Section: Data Definitions to replace the abstract symbols in the models identified in Section: Theoretical Models and Section: General Definitions.
The goal GS: Determine-Linear-Properties is met by IM: transMot and IM: col2D. The goal GS: Determine-Angular-Properties is met by IM: rotMot and IM: col2D.
| Refname | IM:transMot |
|---|---|
| Label | Force on the translational motion of a set of 2d rigid bodies |
| Input | vi, t, g, Fi, mj |
| Output | ai |
| Input Constraints | vi > 0 t > 0 g > 0 Fi > 0 mj > 0 |
| Output Constraints | |
| Equation | ai = dvi(t) dt = g&plusFi(t)mj |
| Description | |
| Notes | The above equation expresses the total acceleration of the rigid body A: objectTy A: objectDimension i as the sum of gravitational acceleration (GD3) and acceleration due to applied force Fi(t) (T1). The resultant outputs are then obtained from this equation using DD: linDisp DD: linVel DD: linAcc. It is currently assumed that there is no damping A: dampingInvolvement or constraints A: constraintsAndJointsInvolvement involved. DD: ctrOfMass. |
| Source | -- |
| RefBy |
| Refname | IM:rotMot |
|---|---|
| Label | Force on the rotational motion of a set of 2D rigid body |
| Input | ω, t, τi, I |
| Output | α |
| Input Constraints | ω > 0 t > 0 τi > 0 I > 0 |
| Output Constraints | α > 0 |
| Equation | α = dω(t) dt = τi(t)I |
| Description | |
| Notes | The above equation for the total angular acceleration of the rigid body A: objectTy A: objectDimension i is derived from T5, and the resultant outputs are then obtained from this equation using DD: angDisp DD: angVel DD: angAccel. It is currently assumed that there is no damping A: dampingInvolvement or constraints A: constraintsAndJointsInvolvement involved. A: axesDefined |
| Source | -- |
| RefBy |
| Refname | IM:col2D |
|---|---|
| Label | Collisions on 2D rigid bodies |
| Input | t, j, mA, n |
| Output | tc |
| Input Constraints | t > 0 j > 0 mA > 0 n > 0 |
| Output Constraints | vA > 0 tc > 0 |
| Equation | vA(tc) = vA(t)&plus jmA n |
| Description | |
| Notes | This instance model is based on our assumptions regarding rigid body A: objectTy A: objectDimension collisions A: collisionType Again, this does not take damping A: dampingInvolvement or constraints A: constraintsAndJointsInvolvement into account. A: axesDefined. DD: ctrOfMass DD: impulse |
| Source | -- |
| RefBy |
Table:InDataConstraints shows the data constraints on the input variables. The column for physical constraints gives the physical limitations on the range of values that can be taken by the variable. The uncertainty column provides an estimate of the confidence with which the physical quantities can be measured. This information would be part of the input if one were performing an uncertainty quantification exercise. The constraints are conservative, to give the user of the model the flexibility to experiment with unusual situations. The column of typical values is intended to provide a feel for a common scenario. FIXME
| Var | Physical Constraints | Typical Value | Uncert. |
|---|---|---|---|
| CR | 0 ≤ CR ≤ 1 | 0.8 | 10% |
| F | -- | 98.1 N | 10% |
| G | -- | 9.8 m3/(kg⋅s2) | 10% |
| I | I ≥ 0 | 74.5 kg⋅m2 | 10% |
| L | L ≥ 0 | 44.2 m | 10% |
| m | m ≥ 0 | 56.2 kg | 10% |
| p | -- | 0.412 m | 10% |
| v | -- | 2.51 m/s | 10% |
| τ | -- | 200.0 N⋅m | 10% |
| ω | -- | 2.1 rad/s | 10% |
| ϕ | -- | π2 rad | 10% |
Input Data Constraints
Table:OutDataConstraints shows the data constraints on the output variables. The column for physical constraints gives the physical limitations on the range of values that can be taken by the variable.
| Var |
|---|
| p |
| v |
| ϕ |
| ω |
Output Data Constraints
This section provides the functional requirements, the tasks and behaviours that the software is expected to complete, and the non-functional requirements, the qualities that the software is expected to exhibit.
This section provides the functional requirements, the tasks and behaviours that the software is expected to complete.
This section provides the non-functional requirements, the qualities that the software is expected to exhibit.
This section lists the likely changes to be made to the software.
This section lists the unlikely changes to be made to the software.
As mentioned in Section: Problem Description, there already exist free open source game physics libraries. Similar 2D physics libraries are:
Free open source 3D game physics libraries include:
The purpose of the traceability matrices is to provide easy references on what has to be additionally modified if a certain component is changed. Every time a component is changed, the items in the column of that component that are marked with an "X" should be modified as well. Table:TraceMatAvsAll shows the dependencies of data definitions, theoretical models, general definitions, instance models, requirements, likely changes, and unlikely changes on the assumptions. Table:TraceMatRefvsRef shows the dependencies of data definitions, theoretical models, general definitions, and instance models with each other. Table:TraceMatAllvsR shows the dependencies of requirements, goal statements on the data definitions, theoretical models, general definitions, and instance models.
Traceability Matrix Showing the Connections Between Assumptions and Other Items
Traceability Matrix Showing the Connections Between Items and Other Sections
Traceability Matrix Showing the Connections Between Requirements, Goal Statements and Other Items
There are no auxiliary constants.
In [ ]: