BXG BLUX Game Engine Getting Started BXG Getting Started

Transcription

1 BXG Getting Started 1. Setup General Tools Downloading BXG SDK Downloading Sample Games Step-by-Step Example of Game Source Writing Constructing Game working directory Writing Game HTML file Writing Game Source Javascript Setup Game Running Game Writing Game Logic Execution Game in Web browser Next Step

2 1. Setup 1.1. General Tools Editor First, you need a general purpose editor for writing game source. That editor has to support UTF-8 encoding. If that editor can understand HTML and Javascript language, it will be good. Web Browser Next, you need to install web browsers such as Chrome, Safari, Opera, Firefox and IE. Web browser itself is one of the execution environments for running game. And it is also a very important development tool, which contains useful tools such as console, HTML Document Element inspection, and debugger. Most of current browsers support those development tools internally or in the form of extension. You d better to run your game source on as many browsers as possible. 2

3 1.2. Downloading BXG SDK BXG SDK packages are released through repositories on GitHub server. You can download the latest version of BXG SDK packages by pressing the download button of Download Page in BXG home. Or you can access the BXG SDK repositories on GitHub server for downloading BXG SDK. Figure 1 How-to download from BXG home. 1. Visit BXG Home -> Download 2. Press the download button (See red box marked button in the above screen shot, Figure 1). Then BXG SDK files will be downloaded as the form of zipped file. 3. Unzip the downloaded zip file and save the BXG SDK files in the directory you want to save (for example, working directory of your game). How-to download from GitHub repository 1. Visit our BXG GitHub repository. 3

4 2. Press the download button in the GitHub repository page. (See red box marked part in following screen shot.) Then you can download zipped BXG SDK files. 3. Unzip the downloaded zip file and save the BXG SDK files in the directory you want to save (for example, working directory of your game) Figure 2 BXG Javascript Library Download the latest version of BXG javascript library from BXG home download page or following BXG javascript library release repository in GitHub,. If you unzip the downloaded file, then you can find the following two javascript files in bx/ directory. BXG Javascript library files names are release-version-post-fixed and the javascript files are minified by using javascript tools such as YUI compressor and so on. BULX for BXG javascript file (ex. blux-bxg js) BXG core javascript file (ex. bxg-core js) 4

5 Figure 3 BXG-Run for Android BXG-Run for Android is our proprietary WRT (Web-Run-Time) for building native-like hybrid game and running it on Android devices. Download the latest version of WRT for Android from the download page of BXG home or following BXG-Run for Android repository in GitHub. If you unzip the downloaded file, then you can find the following bxg-wrt-1.0.jar file in it. Figure 4 Refer Hybrid App Build with BXG-Run Android document of BXG Home > Documents page for more learning. BXG-Run for ios BXG-Run for ios is our proprietary WRT (Web-Run-Time) for building native-like hybrid game and running it on ios devices such as iphone or ipad. Download the latest version BXG-Run for ios from the download page of BXG home or the following BXG-Run for ios repository in GitHub

6 If you unzip the downloaded file, then you can find the following zip file in it. Figure 5 Refer Hybrid App Build with BXG-Run for ios document of BXG Home > Documents page for more learning Downloading Sample Games BXG sample games are provided to help for you to understand how to develop game source powered by BXG. Currently, three sample games are opened to the public for Release 1. Sample game snake This is very basic game for showing overall game structure of BXG at a glance. This game includes very basic usage of BXG features. From this sample game, you can learn about: how to use basic game elements, such as Game Control, Game Object and so on. how to manage assets such as images and sound. how to define and handle input device events. Download the latest version of sample game package, from the download page of BXG home or sample game repository in GitHub. If you unzip the downloaded file, then you can find as the followings: Game Source javascript file : main.js Game HTML file(s): main.html and etc. BXG javascript library files : bx/ directory 6

7 Asset files: imgs/ and sound/ directory Figure 6 Sample game shooting This game is 2-layered 1-way buffered scroll example using BXG. From this sample game, you can learn about: how to use the various BXG game object classes. the collision detection scheme between game objects. how to create the game objects gradually as the map is scrolled. how to handle the game object s sprite states depending on its behavior. Download the latest version of sample game, from the download page of BXG home or each sample game repository in GitHub. If you unzip the downloaded file, then you can find as the followings: Game Source javascript file : main.js Game HTML file: main.html BXG javascript library files : bx/ directory Asset files: imgs/ directory 7

8 Figure 7 Sample game dragon This game shows the scroll type of all kinds provided by BXG. You can run this game in one of the following four scroll modes: 4 way scroll mode no buffered 4 way buffered scroll mode 2 way buffered horizontal scroll mode 2 way buffered vertical scroll mode From this sample game, you can learn about: how to use the various BXG game control classes. how to use mini map. Download the latest version of sample game, from the download page of BXG home or each sample game repository in GitHub. If you unzip the downloaded file, then you can find as the followings: Game Source javascript file : main.js Game HTML file: main.html BXG javascript library files : bx/ directory Asset files: imgs/ directory 8

9 Figure 8 2. Step-by-Step Example of Game Source Writing In this chapter, the overall game structure and development procedure will be shown you step-by-step by using sample game snake. Follow the steps in this tutorial Constructing Game working directory First, you should construct: the game working directory bx/ directory which includes downloaded BXG javascript library release game source javascript file(s) and game html files which you should develop asset directories such as image and sound resources. Step 1 Make a new directory for game in the path where you want. In this tutorial, the name of that directory is bxg.tutorial. Step 2 Copy assets such as image and sound resource files for this tutorial under the game directory bxg.tutorial you made in previous step. You can get those asset files from downloaded zip file of sample game Snake. Step 3 Install the latest version of BXG javascript library files in bx directory under the game directory bxg.tutorial you make in previous step. If you complete from step1 to step 3, you will have a directory that looks something like this. 9

10 Figure Writing Game HTML file Next step is writing the new game HTML file in the game directory bxg.tutorial by using editor. 10

11 The game HTML file is the first part of game invoked from web execution such as web browsers and so on. You can select the name of game HTML file as you want, or as needed in your build environment. In this tutorial, the name of game HTML file is main.html. Here is the typical content of game HTML file. Step1 Add <script> tags for BXG javascript library files. Line 13 ~14 <script type="text/javascript" src="bx/blux-bxg js"></script> <script type="text/javascript" src="bx/bxg-core js"></script> Note The order of <script> tags of BXG javascript library files must be kept as the above. Step2 Add <script> tags for game source javascript files. Line 15 <script type="text/javascript" src="main.js"></script> In this tutorial, game source consists of only one javascript file. But in case of large game, game source may be composed of a large number of files with the directory hierarchy. Note Make sure the <script> tags for game source are after <script> tags for BXG javascript library files. Step3 Add Game Title. Line 20 <title>bxg Sample Game - Snake</title> Step4 Invoke BXG loader inside onload event hander of document.body. Line 22 <body style="background-color:#000000" onload="bxg.load(debug:true);"> 11

12 Note You can give debug:true option when running bxg.load() as the above in order to set the log level of the BXG module as DEBUG. You should use this option only in development phase. When you release the game, you must remove this option to achieve the performance efficiency Writing Game Source Javascript Next, you should write your own game source javascript file for implementing game logic. You can select the name of game source javascript file as you want. But you should match the name of file with <script> tags in game HTML files. Step1 Make a new file of game source javascript main.js under the game directory Setup Game Step2 Define bxg.ongame() function. bxg.ongame() function is the first part of game source invoked by BXG Loader. In this function, the overall game initializing is executed including BXG module initializing. In this tutorial, the codes shown in the steps from 2-1 to 2-6 are written in bxg.ongame() function. 12

13 // Main game logic. This will be called after loading of BXG. /* zindex band of this game 0: food object 1: snake object */ bxg.ongame = function() // Add the source codes in step 2-1 // Add the source codes in step // Add the source codes in step 2-6 Step 2-1 Define the game configuration variables in bxg.c namespace. In this tutorial, for example, the tick interval, game screen size and the dimension of snake game object. The following codes are included in bxg.ongame() function. // Configurations bxg.c.tick = 100; // in msec bxg.c.scrsize = w:480, h:320; // game screen size bxg.c.sizesnake = 10; // dimension size of each circle that comprise the snake body Step 2-2 Initialize BXG module. Call bxg.init() with options such as the game screen size and position, the renderer mode. After BXG module initialization, this sample code shows you can change the background color of the game screen by using HTML/CSS. You may display the game intro page at this moment. // Initialize BXG engine, aligning in page center bxg.init(x:0, y:0, w:bxg.c.scrsize.w, h:bxg.c.scrsize.h, renderer:'domcanvas', align:x:'center', y:'center'); // Set background color of game world by HTML CSS (This is very simple way to change it) // (or it can be done by CImageObject) bxg.playground.style.backgroundcolor = '#aacc99'; Step 2-3 Define Input Device Event and sound effect. You can define the input device events for affecting the snake s movement by using bxg.game.addinputdevice() method. Notice that adding input device events in this step makes BXG ready to handle those input events. To receive input events occurred, 13

14 the event handlers should be written as a member function of Game Control Manger as in later step. For adding the game sound effect, first you should create BXG game sound object by using bxg.csound Class as shown in this sample code. You can play and stop at any time as you want afterward. // This game is only for keyboard device bxg.game.addinputdevice(new bxg.ckeydevice( moveup:key:'keyup', type:'event', movedown:key:'keydown', type:'event',moveleft:key:'keyleft', type:'event', moveright:key:'keyright', type:'event' )); // Create and register sound effect.(not buffered yet) bxg.g.soundeat = new bxg.csound('sound/beep_eat.mp3', 0, 'sound', 1); bxg.g.sounddie = new bxg.csound('sound/beep_die.mp3', 0, 'sound', 1); Step 2-4 Write Object Template. Object Template is an object having all information needed for BXG s Object Factory utility to create game object. In this sample, Object Template for the snake body objects and food object are shown. 14

15 // Object template to be created by ObjectFactory bxg.g.objs = [ type:'obj.body',imagepath:'imgs/snake',images: snake:url:'body.png',info: body:sprite:['snake'],options: manager:isnakemanger,cdshape:[rect:x:0, y:0, w:bxg.c.sizesnake, h:bxg.c.sizesnake],zindex:1, type:'obj.food',imagepath:'imgs/snake',images: food:url:'prey.png', sprite:size:w:10, h:12, cols:4, count:4,info: ready:sprite:['food1', 'food2', 'food3', 'food4'],options: cdshape:[rect:x:0, y:0, w:bxg.c.sizesnake, h:bxg.c.sizesnake],zindex:0 ]; Step 2-5 Register Object Template to Object Factory. // Register object templates to the object factory for(var obj = 0; obj < bxg.g.objs.length; obj ++) bxg.objectfactory.register(bxg.g.objs[obj]); After this step, BXG became to know how to create Game Objects of which type is obj.body or obj.food.. Step 2-6 Load Image Resources in cache-area. All image resources should be loaded in cache-area before being used in game. Image files listed in Object Template are likewise loaded in advance. // Load image resource of ObjectFactory-managed game objects bxg.objectfactory.load(['obj.body', 'obj.food'], onloadobjects); 15

16 In this sample code, bxg.objectfactory.load() method should cause BXG to load image resources which are have already been registered to Object Factory in previous step. When the loading of all of images completes, BXG loader will invoke the callback function ( onloadobjects in this sample case) passed as second parameter of bxg.objectfactory.load() method. Now, game initialization has been completed Running Game After completion of loading images, you are ready to run game. In onloadobject(), write the codes for running game. Step3 Make Game Control and run Game. Game control is main game logic for controlling the game screen and game objects. In this sample, basic CControl is used, which has no scroll and buffering feature for simplicity. IGameManager is the Game Control Manager and its contents are written in step 4 in section // control manager, this manager will control main game logic. IGameManager = function onloadobjects(/*number*/loaded, /*Number*/failed) bxg.g.ctlgame = new bxg.ccontrol(igamemanager).create(); // Game start bxg.game.init(tick:bxg.c.tick); bxg.game.addcontrol(bxg.g.ctlgame); bxg.game.run(); Writing Game Logic Game Control Manager is responsible for the control over the game screen and overall game logic. On the other hand, Game Object Manager is responsible for the control over specific game object. 16

17 After game is running by calling bxg.game.run(), the game source operates in an eventdriven manner. BXG invokes the interface function per BXG specific event defined as a member function of Game Control Manager and Game Object Manager. Step4 Writing Game Control Manager The overall structure of IGameManager in this sample is like this: // control manager, this manager will control main game logic. IGameManager = /* Control Manager Interface functions */ oninputevent: function(/*ccontrol*/ctrl, /*Object*/evtMap) /* see step 4-1, ontick: function(/*ccontrol*/ctrl, /*Number*/tickId) /* see step 4-2, onreset: function(/*ccontrol*/ctrl) // see step 4-3 /* Other user-defined functions */,restartgame: function() // see step 5-1,putFood: function(/*ccontrol*/ctrl) /* see step 5-2 */,addbody: function(/*ccontrol*/ctrl) /* see step 5-3 */ Each member function is described in subsequent sub-steps. Step 4-1Writing IGameManager.onReset() onreset() interface function is called whenever game is (re)run by bxg.game.run(). In this sample, obj.body which composes snake body and obj.food which is food of snake are created and added to game screen. 17

18 onreset: function(/*ccontrol*/ctrl) var i; // Cleanup data of previous run by destroying objects. // (This is just a simple way, it will be better to just remove from game control and add it again.) if(ctrl.data.snake) for(i = 0; i < ctrl.data.snake.length; i ++) ctrl.data.snake[i].destroy(); delete ctrl.data.snake; // Init internal data ctrl.data.snake = []; ctrl.data.dx = -1; // To Left ctrl.data.dy = 0; // Creating the snake body. Start with 17 nodes in body. for(i = 0; i < 17; i ++) this.addbody(ctrl, x:math.floor(bxg.geo.w/2/bxg.c.sizesnake), y:math.floor(bxg.geo.h/2/bxg.c.sizesnake)); this.putfood(ctrl); Notice that the variables related to this game control are defined in namespace ctrl.data. And Two functions this.addbody() and this.putfood() are not the BXG Control Manager interface function but the part of user game logic. Step 4-2 Writing IGameManager.onTick() function. ontick() interface function is called on every tick. In this sample, the snake is moved and drawn according to the current setting. 18

19 ontick: function(/*ccontrol*/ctrl, /*Number*/tickId) // Move snake by put the tail into the head position. // And, only the head will have collistion detection function. ctrl.data._pop = ctrl.data.snake.pop(); ctrl.data._pop.data.pos.x = ctrl.data.snake[0].data.pos.x + ctrl.data.dx; ctrl.data._pop.data.pos.y = ctrl.data.snake[0].data.pos.y + ctrl.data.dy; ctrl.data.snake[0].data.collision = false; ctrl.data._pop.data.collision = true; ctrl.data.snake.unshift(ctrl.data._pop); Step 4-3 Writing IGameManager.onInputEvent() function. oninputevent() receives the events which have been added in previous step. oninputevent: function(/*ccontrol*/ctrl, /*Object*/evtMap) if (evtmap.moveleft && evtmap.moveleft.fired && ctrl.data.dx!= 1) ctrl.data.dx = -1; ctrl.data.dy = 0; else if (evtmap.moveright && evtmap.moveright.fired && ctrl.data.dx!= -1) ctrl.data.dx = 1; ctrl.data.dy = 0; else if (evtmap.moveup && evtmap.moveup.fired && ctrl.data.dy!= 1) ctrl.data.dx = 0; ctrl.data.dy = -1; else if (evtmap.movedown && evtmap.movedown.fired && ctrl.data.dy!= -1) ctrl.data.dx = 0; ctrl.data.dy = 1; Step5 Writing other non-bxg-interface functions if need. Step 5-1 Writing restartgame() function. restartgame: function() bxg.g.sounddie.play(); bxg.game.end(); bxg.game.run(); 19

20 Step 5-2Writing putfood() function. putfood: function(/*ccontrol*/ctrl) // Put // Put food in view screen and away 4-grids distance from any snake body. if (!ctrl.data.objfood) ctrl.data.objfood = bxg.objectfactory.build('obj.food'); ctrl.add(ctrl.data.objfood); ctrl.data._setfood = false; ctrl.data._posfood = ctrl.data._posfood x:0, y:0; while(!ctrl.data._setfood) ctrl.data._posfood.x = Math.floor(Math.random()*bxg.geo.w/bxg.c.sizeSnake); ctrl.data._posfood.y = Math.floor(Math.random()*bxg.geo.h/bxg.c.sizeSnake); if (bxg.geometry.getdistance(ctrl.data._posfood, ctrl.data.snake[0].data.pos) > 4) ctrl.data._setfood = true; ctrl.data.objfood.move( ctrl.data._posfood.x*bxg.c.sizesnake, ctrl.data._posfood.y*bxg.c.sizesnake); if (!ctrl.data.objfood.active) ctrl.data.objfood.activate(); ctrl.data.objfood.show(); Step 5-3 Writing addbody() function. addbody: function(/*ccontrol*/ctrl, /*Object undefined*/pos) // Add snake body. var obj; // Create snake body and add to tail. ctrl.add(obj = bxg.objectfactory.build('obj.body')); if (pos) obj.data.pos = pos; else // Add to tail obj.data.pos = x:ctrl.data.snake[ctrl.data.snake.length-1].data.pos.x, y:ctrl.data.snake[ctrl.data.snake.length-1].data.pos.y; obj.activate(); ctrl.data.snake.push(obj); 20

21 Step6 Writing Game Object Manager Interface functions The overall structure of ISnakeManager in this sample is like this: ISnakeManger = onactivate: function(/*object*/obj, /*Number*/tickId) /* See step 6-1 */,ontick: function(/*object*/obj, /*Number*/tickId) /* See step 6-2 */,oncollision: function(/*object*/obj, /*Object*/hit) /* See step 6-3 */,onoutview: function(/*object*/obj) /* See step 6-4 */ Step 6-1 Writing ISnakeManager.onActivate() function onactivate: function(/*object*/obj, /*Number*/tickId) obj.move(obj.data.pos.x*bxg.c.sizesnake, obj.data.pos.y*bxg.c.sizesnake); obj.show(); Step 6-2 Writing ISnakeManager.onTick() function,ontick: function(/*object*/obj, /*Number*/tickId) obj.move(obj.data.pos.x*bxg.c.sizesnake, obj.data.pos.y*bxg.c.sizesnake); Step 6-3 Writing ISnakeManager. oncollision () function,oncollision: function(/*object*/obj, /*Object*/hit) if (!obj.data.collision) return; if (hit.type == 'obj.food') bxg.g.soundeat.play(); IGameManager.putFood(bxg.g.ctlGame); IGameManager.addBody(bxg.g.ctlGame); else if (hit.type == 'obj.body') IGameManager.restartGame(); Step 6-4 Writing ISnakeManager. onoutview ()function,onoutview: function(/*object*/obj) IGameManager.restartGame(); 21

22 2.4. Execution Game in Web browser You can run the snake game written in this tutorial by typing the full path of the game html in the address bar or by double clicking the game html file. 3. Next Step BXG Core Developer Guide Building hybrid app with BXG-Run for Android or ios Building hybrid app with Phonegap for Android or ios 22

23 23