LibGDX. André Restivo 1 / 87

Transcription

1 LibGDX André Restivo 1 / 87

2 Index Introduction Core Modules Life-Cycle 2D Graphics Camera Physics Input Handling Scene 2d Collisions Sound Animations Testing 2 / 87

3 Introduction 3 / 87

4 LibGDX A Java game development framework providing a unified API that works across several different platforms: Desktop: Windows, Linux, Mac OS X Mobile: Android, BlackBerry, ios Web: Java Applet, Javascript/WebGL Can be used in many different ways as it does not force a specific design on you. 4 / 87

5 Environment Setup Start by downloading the LibGDX Setup App. To open it, double-click the downloaded.jar file or use java -jar gdx-setup.jar from the command line. If you want to have Android support, you must also have the Android SDK installed. The easiest way is to install Android Studio. 5 / 87

6 Setup App 6 / 87

7 Assets The setup app creates a different project for each selected platform plus a Core project where you will write the bulk of your code. In order to share assets between the different projects, only one assets folder is created. If you select Android as a supported platform, this folder will be located in the Android project. If not, it will be located in the Core project. You might have to change the working directory of each project to the assets folder in your IDE of choice. 7 / 87

8 Core Modules 8 / 87

9 Core Modules The Gdx class provides a unified interface to all the supported platforms: Input - Provides an input model and handler for all platforms (keyboard, touchscreen, accelerometer, mouse,...). Gdx.input.getAccelerometerX() Graphics - Enables the drawing of images to the screen using the hardware provided OpenGL ES implementation. Gdx.graphics.isFullscreen() Gdx.gl.glClearColor(); Files - Abstracts file access on all platforms by providing convenient methods for read/ write operations. Gdx.files.internal() Audio - Facilitates sound recording and playback on all platforms. Gdx.audio.newSound() Networking - Provides methods to perform networking operations, such as simple HTTP get and post requests, and TCP server/client socket communication. Gdx.net.newServerSocket() 9 / 87

10 Core Modules Core modules are not only used by the app being developed, but also by the internal LibGDX code. [Not supported by viewer] upported by viewer] [Not supported by viewer] [Not supported by viewer] [Not supported by viewer] [Not supported by viewer] [Not supported by viewe [Not supported by viewer] 10 / 87

11 Application Life-Cycle 11 / 87

12 Starter Classes For each target platform, a starter class is automatically generated by the setup application. Normally we don't have to modify these classes unless we want to change some configuration items. Example desktop starter class: public class Main { public static void main(string[] args) { LwjglApplicationConfiguration cfg = new LwjglApplicationConfiguration(); cfg.title = "My Game"; cfg.usegl30 = false; cfg.width = 480; cfg.height = 320; } } new LwjglApplication(new MyGame(), cfg); 12 / 87

13 ApplicationListener An ApplicationListener allows you to handle application events. This allows you to execute code during certain events within the game life-cycle. public interface ApplicationListener { public void create (); // When the game is created public void render (); // When the game should render a frame public void resize (int width, int height); // When the game is resized public void pause (); // When the game loses focus (android only) public void resume (); // When the game regains focus (android only) public void dispose (); // When the games is closed } 13 / 87

14 Life Cycle Application Start create() resize() resume() Regained Focus<div>(android)</div> render() Application Running [Not supported by viewer] pause() Application Closing pause() dispose() Application Stop 14 / 87

15 ApplicationAdapter An abstract class that implements the ApplicationListener interface. Allows the developer to implement the ApplicationListener interface without overriding every method. public abstract class ApplicationAdapter implements ApplicationListener { } /*... */ 15 / 87

16 Game A Game is an ApplicationListener that supports multiple screens. You can create multiple screens and switch between them using setscreen. Game events are delegated to the current screen. public abstract class Game implements ApplicationListener { } public void setscreen(screen screen); public Screen getscreen(); /*... */ 16 / 87

17 Screen Represents one of many application screens, such as a main menu, a settings menu, the game screen and so on. public interface Screen { public void public void public void public void public void public void public void dispose(); hide(); pause(); render(float delta); // delta in seconds since the last render. resize(int width, int height); resume(); show(); } 17 / 87

18 ScreenAdapter An abstract class that implements the Screen interface. Allows the developer to implement the Screen interface without overriding every method. public abstract class ScreenAdapter implements Screen { } /*... */ 18 / 87

19 Proposed Usage «interface»<div>applicationlistener</div> [Not supported by viewer] + create() : void + pause() : void + dispose() : void + render() : void + resize(int width, int height) : void + resume() : void [Not supported by viewer] + setscreen(screen screen) : void + getscreen() : Screen * + dispose() + hide() + pause() + render(float delta) + resize(int width, int height) + resume() + show() «abstract»<div>applicationadapter</div> [Not supported by viewer] <div>mygame</div> <div>mainmenuscreen</div> <div>gamescreen</div> Our Game Classes 19 / 87

20 2D Graphics 20 / 87

21 SpriteBatch It is very common to draw a texture mapped to rectangular geometry. It is also very common to draw the same texture or various regions of that texture many times. It would be inefficient to send each rectangle one at a time to the GPU to be drawn. Instead, many rectangles for the same texture can be described and sent to the GPU all at once. This is what the SpriteBatch class does. public class SpriteBatch implements Batch { public void begin (); public void draw(texture texture, float x, float y); // and many other like this public void end(); public void dispose(); } 21 / 87

22 Texture The Texture class decodes an image file and loads it into GPU memory. public class Texture extends GLTexture { } Loading a texture into memory: Texture herotexture = new Texture (Gdx.files.internal("hero.png")); Textures should be disposed once they are not needed: herotexture.dispose(); 22 / 87

23 TextureRegion The TextureRegion class describes a rectangle inside a texture and is useful for drawing only a portion of the texture. public class TextureRegion { public TextureRegion (TextureRegion region, int x, int y, int width, int height); public void setregion (int x, int y, int width, int height); } public static TextureRegion[][] split (Texture texture, int tilewidth, int tileheight); The split method is an helper method that splits a Texture into TextureRegions according to a tile width and height. 23 / 87

24 Sprite The Sprite class describes both a texture region and the geometry where it will be drawn. public class Sprite extends TextureRegion { public Sprite (TextureRegion region); public void setposition (float x, float y); public void setcenter(float x, float y); public void setrotation (float degrees); public void setscale (float scalexy); } public void draw (Batch batch); 24 / 87

25 Texture Classes GLTexture [Not supported by viewer] Texture 1 TextureRegion Sprite 25 / 87

26 AssetManager Textures take a lot of precious memory. The same texture is typically used more than once. The AssetManager can manage our textures keeping only one copy of each in memory. It also handles asynchronous loading. public class AssetManager implements Disposable { public <T> void load (String filename, Class<T> type); public <T> T get (String filename); } public boolean update(); // true if finished loading public void finishloading (); // waits for all assets to load 26 / 87

27 Render To render our Screen we can do something like: // In our screen class: public void render(float delta) { super.render(delta); // Clear the screen Gdx.gl.glClearColor( 103/255f, 69/255f, 117/255f, 1 ); Gdx.gl.glClear( GL20.GL_COLOR_BUFFER_BIT GL20.GL_DEPTH_BUFFER_BIT ); } // Draw the texture game.getbatch().begin(); game.getbatch().draw(texture, 100, 100); game.getbatch().end(); Delta is the time in seconds since the last render. 27 / 87

28 Example As an example lets checkout the texture branch on this example project: In particular the BouncingScreen class. 28 / 87

29 Camera 29 / 87

30 Units Every device has a different screen size and ratio. This means that we cannot think in terms of pixels to define the size of our objects. A sugestion for dealing with this problem: public static int WORLD_WIDTH = 100; // Arbitrary world size (e.g. meters) public static int WORLD_HEIGHT = 50; // The ammount of world we want to show in our screen public static int VIEWPORT_WIDTH = 50; public static int VIEWPORT_HEIGHT = 25; // Can be calculated from screen ratio // How to transform from pixels to our unit public static int PIXEL_TO_METER =.05f; float ratio = ((float)gdx.graphics.getheight() / (float)gdx.graphics.getwidth()); 30 / 87

31 Example For example: A world of 100x50(m). On a 1280x720(px) screen. With a viewport 50m wide. And showing a 50x50(px) texture. Where a pixel is equal to.05m. We would get: The world would have 2560x2048 pixels. The screen ratio would be The viewport would be 1280x720(px) or 50x28.1(m). The texture would represent 2.5x2.5(m). The texture would be drawn as 64x64(px) (2.5/50*1280). 31 / 87

32 Orthographic Camera The viewport into our game. Implements a parallel (orthographic) projection. public class OrthographicCamera extends Camera { public OrthographicCamera (float viewportwidth, float viewportheight); public void update (); // Updates the transformation matrix } Setting the camera position: camera.position.set(new Vector3(x, y, 0)); 32 / 87

33 Example As an example lets checkout the camera branch on this example project: In particular the BouncingScreen class. 33 / 87

34 Physics 34 / 87

35 World The World class manages all physics entities using Box2D. public final class World implements Disposable { public World (Vector2 gravity, boolean dosleep); public Body createbody (BodyDef def); public void destroybody (Body body); } The world uses SI units (meters, Newtons, seconds, radians,...) 35 / 87

36 Body In Box2D the physical objects are called bodies. Bodies can be of three types: Dynamic: move around and are affected by forces and other dynamic, kinematic and static objects (example: hero, enemies,...). Static: do not move and are not affected by forces (but affect dynamic objects (examples: ground, platform, wall,...). Kinematic: do not react to forces, but have the ability to move (example: a moving plaform). 36 / 87

37 Body Definition To create a body we first must create a body definition. A body definition holds all the data needed to construct a rigid body. You can safely re-use body definitions. BodyDef bodydef = new BodyDef(); bodydef.type = BodyDef.BodyType.DynamicBody; bodydef.angle = (float) (Math.PI / 4); // radians bodydef.position.set(10f, 5f); // meters bodydef.linearvelocity.set(5f, 0f); // meters/s bodydef.angularvelocity.set(math.pi); // PI radians/s Body body = world.createbody(bodydef); 37 / 87

38 Fixtures Each body is made up of one or more fixtures, which have a fixed position and orientation within the body. Fixtures give bodies their shape, mass and properties. // Create shape CircleShape circle = new CircleShape(); circle.setradius(0.22f); //22cm // Create fixture FixtureDef fixturedef = new FixtureDef(); fixturedef.shape = circle; fixturedef.density =.5f; // how heavy is the fixture kg/m^2 fixturedef.friction =.5f; // how slippery is the fixture [0,1] fixturedef.restitution =.5f; // how bouncy is the fixture [0,1] // Attach ficture to body body.createfixture(fixturedef); 38 / 87

39 Shapes There are 4 types of shapes that can be used to create fixtures: Circle: A circle with a radius. Edge: A line segment. Chain: A chain of line segments. Polygon: A convex polygon. 39 / 87

40 Circle Shape Circles have a radius: CircleShape circle = new CircleShape(); circle.setradius(0.11f); 40 / 87

41 Polygon Shape Polygon shapes must be convex and can have 8 vertexes at most. They can be combined to create more complex shapes. public class PolygonShape extends Shape { public void set (Vector2[] vertices); } Creating a rectangular shape is easy with the setasbox method. PolygonShape rectangle = new PolygonShape(); rectangle.setasbox(1f, 0.5f); 41 / 87

42 Updating the world To update our simulation we need to tell our world to step. Stepping updates the world objects through time. The best place to call our step function is at the end of our render loop. public final class World implements Disposable { public void step ( float timestep, // time since last update int velocityiterations, // accuracy for velocity constraints (6) int positioniterations); // accuracy for position constraints (2) } 42 / 87

43 Example As an example lets checkout the physics and ground branches on this example project: In particular the BouncingScreen (physics) and BouncingScreen (ground) classes. 43 / 87

44 Direct Movement We can change the position, angle and speed of a body directly: public void settransform (Vector2 position, float angle); // meters, radians public void setlinearvelocity (Vector2 velocity); // meters/second public void setangularvelocity (float omega); // radians/second 44 / 87

45 Forces and Impulses But normally, to move things around, we will apply forces or impulses to a body. Forces act gradually over time to change the velocity of a body. Impulses change a body's velocity immediately. public class Body { public void applyforce (Vector2 force, Vector2 point, boolean wake); // Newtons public void applyforcetocenter (Vector2 force, boolean wake); // Newtons public void applylinearimpulse (Vector2 impulse, Vector2 point, boolean wake); //Newtons*second } 45 / 87

46 Torque Angular movement can also be controlled: Torques act gradually over time to change the angular velocity of a body. Impulses change a body's angular velocity immediately. public class Body { public void applytorque (float torque, boolean wake); //Newton*meter public void applyangularimpulse (float impulse, boolean wake); //kg*m²/second } More on Box2D 46 / 87

47 Input Handling 47 / 87

48 Keyboard In each step of our simulation we can check if some key of the keyboard has been pressed using the Input interface. public interface Input { public boolean iskeypressed (int key); public boolean iskeyjustpressed (int key); } The Input interface also has keycodes for every key: Input.isKeyPressed( Input.Key.NUM_0 ); Input.isKeyPressed( Input.Key.A ); Input.isKeyPressed( Input.Key.LEFT ); /*... */ 48 / 87

49 Touch We can also checked if the screen has been touched or clicked: public interface Input { public boolean istouched (); public boolean justtouched (); } And get the touch coordinates: public interface Input { public int getx (); public int gety (); public int getdeltax (); public int getdeltay (); } 49 / 87

50 Example As an example lets checkout the input branch on this example project: In particular the BouncingScreen class. 50 / 87

51 Scene2d 51 / 87

52 Scene2d Scene2d is a 2D scene graph for building applications and UIs using a hierarchy of actors: Rotation and scale is applied to all child actors. Each actor draws in its own un-rotated and unscaled coordinate system where 0,0 is the bottom left corner. Hit (touch, mouse) detection of rotated and scaled actors. Routing of input and other events to the appropriate actor. Action system for easy manipulation of actors over time. 52 / 87

53 Stage The Stage class has a camera, SpriteBatch, and a root group and handles drawing the actors and distributing input events. public class Stage extends InputAdapter implements Disposable { public Stage (Viewport viewport); public void act (float delta); public void draw (); } 53 / 87

54 Viewport Manages a Camera and determines how world coordinates are mapped to and from the screen. Many types of viewports can be used: StretchViewport FitViewport FillViewport ScreenViewport 54 / 87

55 StrechViewport The StretchViewport supports working with a virtual screen size. The virtual viewport will always be stretched to fit the screen. No black bars, but the aspect ratio may not be the same. [Not supported by viewer] [Not supported by viewer] [Not supported [Not supported by view by 55 / 87

56 FitViewport The FitViewport supports working with a virtual screen size. It will always maintain the aspect ratio of the virtual screen size, while scaling it as much as possible to fit the screen. One disadvantage with this strategy is that there may appear black bars. [Not supported by viewer] [Not supported by v [Not supported by viewer] [Not supported by 56 / 87

57 FillViewport The FillViewport supports working with a virtual screen size. Keeps the aspect ratio of the virtual screen size. It will always fill the whole screen. Parts of the viewport might be cut off. [Not supported by viewer] [Not supported by viewer] [Not supported [Not by supported viewer] by v 57 / 87

58 ScreenViewport The ScreenViewport does not have a constant virtual screen size. It will always match the window size. No scaling happens and no black bars appear. A player with a bigger screen might see more of the game, than a player with a smaller screen size. [Not supported by viewer] [Not supported by viewer] 58 / 87

59 Actor The Actor class is a node in the graph which has a position, rectangular size, origin, scale, rotation, and color. public class Actor { public void draw (Batch batch, float parentalpha); public void act (float delta); protected void setstage (Stage stage); } 59 / 87

60 Group The Group class is an actor that may have child actors. public class Group extends Actor { public void addactor (Actor actor); public boolean removeactor (Actor actor); } 60 / 87

61 Widgets LibGDX has a set of predefined actors ready to be used: Image - An image Label - A text label List - A list of textual items with current selection support ProgressBar - The progress of some activity or a value within a range SelectBox - A dropdown list TextField - A single-line input field Touchpad - A virtual joystick scorelabel = new Label("0", new Label.LabelStyle(new BitmapFont(), null)); scorelabel.setcolor(color.white); addactor(scorelabel); 61 / 87

62 Usage initial:screen :Viewport :World :Game game:stage ball:actor game:screen hud:stage ground:actor :Viewport score:actor 62 / 87

63 Events Stage is an InputProcessor. When it receives input events, it fires them on the appropriate actors. Events are propagated in two phases: The capture phase from the root down to the target actor. And the normal phase from the target up to the root. public class Actor { public boolean addlistener (EventListener listener); public boolean removelistener (EventListener listener); public void settouchable (Touchable touchable); public void setvisible (boolean visible); } 63 / 87

64 ClickListener Listens to mouse and touch events. public ClickListener () { public void touchdown(inputevent e, float x, float y, int pointer, int button); public void touchup(inputevent e, float x, float y, int pointer, int button); public void clicked(inputevent e, float x, float y); } public int gettapcount(); 64 / 87

65 ActorGestureListener For more complex touch events. public ActorGestureListener () { public void touchdown(inputevent e, float x, float y, int pointer, int button); public void touchup(inputevent e, float x, float y, int pointer, int button); public void tap(inputevent e, float x, float y, int count, int button); public boolean longpress(actor actor, float x, float y); public void fling(inputevent e, float velocityx, float velocityy, int button); public void pan(inputevent e, float x, float y, float deltax, float deltay); public void zoom(inputevent e, float initialdistance, float distance); public void pinch(inputevent e, Vector2 ipointer1, Vector2 ipointer2, Vector2 pointer1, Vector2 pointer2); } 65 / 87

66 Example As an example lets checkout the stage branch on this example project: In particular the BouncingScreen, GameStage, BallActor and GroundActor classes. 66 / 87

67 Actions Actions can be attached to actors in order to execute a certain operation on the actor for a certain time. When a action finishes, the action is automatically removed from the actor. abstract public class Action { abstract public boolean act (float delta); } Many actions are already implemented in libgdx but more can be added easily: MoveToAction action = new MoveToAction(); action.setposition(x, y); action.setduration(duration); actor.addaction(action); Actions can be composed together to create more complex actions. 67 / 87

68 Example As an example lets checkout the action branch on this example project: In particular the GameStage and BallActor classes. 68 / 87

69 Collisions 69 / 87

70 Collisions To detect collisions between body in the physical world we can implement a ContactListener interface: public interface ContactListener { public void begincontact (Contact contact); public void endcontact (Contact contact); } To use it, just set and implement the contact listener of the physical world: world.setcontactlistener(new ContactListener() public void begincontact(contact contact) { } public void endcontact(contact contact) { } 70 / 87

71 Contact When a collision is detected, the ContactListener receives a Contact class with information about the contact. We can easily get the fixtures that collided: public class Contact { public Fixture getfixturea (); public Fixture getfixtureb (); } And also the bodies: world.setcontactlistener(new ContactListener() public void begincontact(contact contact) { Body bodya = contact.getfixturea().getbody(); Body bodyb = contact.getfixtureb().getbody(); } } The order of the fixtures (and bodies) is not guaranteed! 71 / 87

72 Body User Data User data can be attached to a body to help identify the colliding bodies: public class Body { public Object getuserdata (); public void setuserdata (Object userdata); } For example: body.setuserdata(actor); And then: Actor actor = (Actor)body.getUserData(); 72 / 87

73 Example As an example lets checkout the collision branch on this example project: In particular the GameStage class. 73 / 87

74 Sound 74 / 87

75 Sound LibGDX supports two main types of sound: Music: represents a streamed audio file. The interface supports pausing, resuming and so on. Sound a short audio clip that can be played numerous times in parallel. Sound sound = Gdx.audio.newSound(Gdx.files.internal("kick.wav")); Music music = Gdx.audio.newMusic(Gdx.files.internal("music.mp3")); All sounds and musics should be disposed when no longer needed: sound.dispose(); music.dispose(); 75 / 87

76 Sound Manager We can use the AssetManager to manage our sounds and musics just like we do with textures: assetmanager.load("kick.wav", Sound.class); assetmanager.load("music.mp3", Music.class); And then: Sound sound = assetmanager.get("kick.wav"); Music music = assetmanager.get("music.mp3"); 76 / 87

77 Playing To play a sound we can use public interface Sound extends Disposable { public long play (); public long play (float volume); // Volume = [0,1] } To play a music: public interface Music extends Disposable { public void setvolume (float volume); public void setlooping (boolean islooping); public void play (); public void pause (); public void stop (); } public boolean isplaying (); 77 / 87

78 Animations 78 / 87

79 Animation An animation consists of multiple frames which are shown in a sequence at set intervals. To create a animation we start by getting a texture and spliting it into TextureRegions: Texture texture = game.getassetmanager().get("animation.png TextureRegion[][] thrustregion = TextureRegion.split( texture, texture.getwidth() / 5, // 5 columns texture.getheight() / 3); // 3 lines 79 / 87

80 Frames We then need to transform the resulting bi-dimensional array into a uni-dimensional array. The easiest way to do it, is to use the System.arraycopy method: public static void arraycopy( Object src, int srcpos, Object dest, int destpos, int length); Like this: TextureRegion[] frames = new TextureRegion[10]; System.arraycopy(thrustRegion[0], 0, frames, 0, 10); 80 / 87

81 Current Frame We then create the animation: // 0.25 seconds per frame Animation animation = new Animation<TextureRegion>(.25f, frames); The current frame is a TextureRegion and we can get it like this: public class Animation { public TextureRegion getkeyframe ( float statetime, // current time boolean looping // should the animation loop ); } 81 / 87

82 Example As an example lets checkout the animation branch on this example project: In particular the BallActor class. 82 / 87

83 Testing 83 / 87

84 Testing LigGDX promotes the mixing of the graphical interface with the model and logic rules of the game. This makes testing harder: Because our classes start by loading their textures, a OpenGL driver must be in use, which may not be possible. A world must be created if physics is being used. Testing units separately is difficult. 84 / 87

85 Model-View-Controller A better way to organize our code is to use the high-level archictural design pattern known as Model-View-Controller (MVC): Controller updates events updates notifies View Model 85 / 87

86 Proposed Architecture The MVC pattern is more suited for gui-driven applications than to games, that normally use a render-loop pattern. For these we propose a slightly different approach: [Not supported by viewer] updates events updates Screen reads Model Screen reads Model 86 / 87

87 Example As an example lets checkout the sprites and physics branch on this example project: / 87