MASARYK UNIVERSITY FACULTY OF INFORMATICS Pinball game in Box2D engine BACHELOR'S THESIS David Kratochv´ıl Brno, 2017 Declaration Hereby I declare that this paper is my original authorial work, which I have worked out by my own. All sources, references and literature used or excerpted during elaboration of this work are properly cited and listed in complete reference to the due source. David Kratochv´ıl Advisor: RNDr. Adam Rambousek, Ph.D. ii Acknowledgements I would like to thank my supervisor RNDr. Adam Rambousek, Ph.D. for leading this thesis, his guidance and advices. Also, I would like to thank Ing. Pavel Tiˇsnovsk´y,Ph.D. for introducing me to this field and helping me to create this work. iii Abstract In this bachelor thesis I deal with the physics engine Box2D and its port into Java JBox2D. My goal is to study features of JBox2D library and then use them to create a simulation of a pinball machine. iv Keywords JBox2D, Box2D, JavaFX, physics engine, game engine v Contents 1 Introduction3 2 Box2D and JBox2D5 2.1 LiquidFun.........................5 2.2 Pooling...........................6 2.3 Serialization........................6 2.4 Phys2D and LibGDX...................6 3 Features of JBox2D8 3.1 Common module.....................8 3.2 Collision module.....................8 3.2.1 AABB.......................9 3.2.2 Shapes.......................9 3.3 Dynamics module..................... 11 3.3.1 Bodies....................... 11 3.3.2 Fixtures...................... 12 3.3.3 Contacts...................... 14 3.3.4 Worlds....................... 14 3.3.4.1 AABB Query.............. 15 3.3.4.2 Ray Casting............... 15 3.3.4.3 Impulses, forces, torques........ 16 3.3.5 Joints....................... 16 4 Application 19 4.1 JavaFX.......................... 19 4.1.1 Availability.................... 19 4.1.2 Coordination system............... 19 4.2 Configuration....................... 20 4.3 Objects.......................... 22 4.4 Contact Listener..................... 27 4.5 Sound effects....................... 27 4.6 Key Input......................... 27 4.7 Frames........................... 28 1 5 Conclusion 29 6 Bibliography 30 2 1 Introduction A simulation is a process, that tries to virtually imitate a situation from the real world and produce the possibly most accurate outcome. Simulations are integral part of researches in many scientific fields like engineering, medicine, or economy. It also plays an important role in education and training of a military personnel. Recently, simulations also found usage in entertainment industry. Video games often contain objects, that need to move on the screen and their motion have to look realistically. Physics simulations not only allow to create scenes with these ob- jects, but also add diverse properties to them and calculate their be- haviour in different environments. These calculations are performed by physical engines. There are many physical engines that can simulate either two or three dimensional scenes. Box2D is a physical engine, that allows to create physically accurate two-dimensional simulations. It has been used in many programs on various platforms. Although Box2D itself was written in C++, it has been ported in many other programming languages like Java, Adobe Flash, C#, or Java Script. Box2D and it's ports are still under developement and continuously gain new features. The application, which is a part of this thesis, is written in Java, and therefore uses Java port of Box2D, called JBox2D. The goal of this thesis is to study how to work with JBox2D library and its components and use it to create an accurate simulation of a pinball machine. The written part of the thesis consists of three chapters describing JBox2D and Box2D libraries, features and objects they work with, and the application itself. First chapter focuses on physical library Box2D and it's Java port JBox2D, components, that these libraries have in common, as well as those, in which they differ. This chapter also offers a preview of some other Java libraries, that are based on Box2D. Second chapter focuses on main features of JBox2D library, it's modules and their components including bodies, fixtures, joints and 3 collisions, their types, behaviour and how to work with them. Third chapter describes the application, individual objects used in the simulation, and how they were created, as well as some difficulties met during the developement. This chapter also focuses on how to work with the application, how the objects are loaded and how to create custom playfield. This part also mentions used graphical user interface and its combination with JBox2D. 4 2 Box2D and JBox2D Box2D [1] is a physics engine, that was created by programmer Erin Catto as a part of his presentation on Game Developer Conference in 2006. This engine is distributed under zlib licence, and is therefore available as a free software on the internet. Although Box2D is written in C++, there are many ports, that allow to use this engine in other programming languages. These ports are created and maintained by the community, which updates them according to the original Box2D engine. JBox2D [2] is a Java port of Box2D. It was created as a combination of Box2D with physics engine LiquidFun [4] and, like Box2D, is also released under zlib licence. 2.1 LiquidFun LiquidFun is a library written in C++, created by Google as an extention of Box2D with added simulation of soft bodies and particle based fluids. Although JBox2D was created as a port of Box2D, today it is closer to the LiquidFun engine. JBox2D is very close to it's original and (except different naming conventions in C++ and Java) there are only few differences in these two libraries. Main distinction are few objects that are supported by one engine but not by the other. For example, as stated before, JBox2D can use small particles connected together, allowing them to simulate water and other liquids or soft bodies that can be deformed under pressure. The application uses older version of JBox2D, and therefore misses few objects from present Box2D. These are, for example, two new joints, called motor and rope joint. Box2D also has more shapes. While Box2D can create edge and chain shaped bodies, JBox2D creates edges only as a special type of polygon shapes, and chains aren't supported at all. All these objects are, however, present in the newest version of JBox2D. JBox2D also, unlike Box2D, features pooling and serialization. 5 2.2 Pooling Pooling [5] allows to manage several instances of one resource in a pool. The pool can store data from the simulation that are not needed in the moment, but could be reused in near future. When the stored object is required, the user can request for it, removing it from the pool. After using it, instead of destroying the object, it can be returned back into the pool again. With this method, it is possible to remove bodies from the simulations and return them back later, instead of creating and destroying them every time they are needed. 2.3 Serialization Serialization [6] is a process, which allows objects to be saved into byte streams. Data stored in these streams have to contain enough in- formation, to recreate the original object. Serialization can be used to make objects persistent, create identical copy of an object, or transfer objects over a network. 2.4 Phys2D and LibGDX Except JBox2D, there are other Java libraries based on Box2D. Phys2D is physics engine based on the earlier version of Box2D, called Box2D Lite. Another option is to use libGDX as a JNI wrapper around Box2D, which allows to work with the library by translating code be- tween two languages. Since Phys2D is based on Box2D Lite, it is much more simple than JBox2D. It isn't maintained anymore, and therefore lacks many fea- tures introduced in later version of Box2D. Although Phys2D is able to create simulations using bodies with various shapes and mass prop- erties, it isn't as precise as JBox2D, and isn't very suitable for more complex simulations. Unlike JBox2D, Phys2D doesn't use continuous collision detection, which causes tunneling effect between objects more often. 6 LibGDX is a Java wrapper around Box2D, and only translates the code between Java and C++. LibGDX is therefore, unlike JBox2D, fully dependable on the native library, and can only use features from Box2D. 7 3 Features of JBox2D Jbox2D creates scenes by generating rigid bodies, modifying their mass properties by attaching fixtures to them and connecting bodies together with joints. Additionally, it also performs mathematics to compute the movement of objects and solve their collisions. All these functions are separated into three modules: Common, Collision and Dynamics. 3.1 Common module Common module contains settings with various values representing maximums of some variables, and constants used by JBox2D. The sim- ulation uses meters, kilograms, and seconds, or shortly MKS units, for calculations of objects and their properties. In code, the majority of these variables are represented as floating-point numbers. This mod- ule also manages types for vectors called Vec2, for two-dimensional vectors, and Vec3 for three-dimensional vectors and performs vector math using matrix modules. Common module is also responsible for memory management. 3.2 Collision module Collision module contains shapes, as well as functions and queries used by them. Before two shapes collide, JBox2D detects these shapes using collision detection. The collision detection system is responsible for calculating when and where the collision takes place and the normal vector between the touching objects [9]. JBox2D computes their points of contact and normal vector, and stores them into a contact manifold. Data from contact manifold are then used by contact solver to calculate the outcome of the collision. During a collision, JBox2D uses method called narrow-phase, to recieve contact points between two shapes.