sdk/jme3-documentation/src/com/jme3/gde/docs/jme3/beginner/hello_simpleapplication.html

   1
   2 <h1><a>jMonkeyEngine 3 Tutorial (1) - Hello SimpleApplication</a></h1>
   3 <div>
   4
   5 <p>
   6
   7 Previous: <a href="/com/jme3/gde/docs/jme3#installing_jmonkeyengine_3.html">Installing JME3</a>,
   8 Next: <a href="/com/jme3/gde/docs/jme3/beginner/hello_node.html">Hello Node</a>
   9 </p>
  10
  11 <p>
  12 <strong>Prerequisites:</strong> This tutorial assumes that you have <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer"><param name="content" value="http://jmonkeyengine.org/wiki/doku.php/"><param name="text" value="<html><u>downloaded the jMonkeyEngine SDK</u></html>"><param name="textColor" value="blue"></object>.
  13 </p>
  14
  15 <p>
  16 In this tutorial series, we assume that you use the jMonkeyEngine <a href="/com/jme3/gde/docs/sdk.html">SDK</a>. As an intermediate or advanced Java developer, you will quickly see that, in general, you can develop jMonkeyEngine code in any integrated development environment (NetBeans IDE, Eclipse, IntelliJ) or even from the <a href="/com/jme3/gde/docs/jme3/simpleapplication_from_the_commandline.html">command line</a>.
  17 </p>
  18
  19 <p>
  20 OK, let&#039;s get ready to create our first jMonkeyEngine3 application.
  21 </p>
  22
  23 </div>
  24 <!-- EDIT1 SECTION "jMonkeyEngine 3 Tutorial (1) - Hello SimpleApplication" [1-726] -->
  25 <h2><a>Create a Project</a></h2>
  26 <div>
  27
  28 <p>
  29
  30 In the jMonkeyEngine <acronym title="Software Development Kit">SDK</acronym>:
  31 </p>
  32 <ol>
  33 <li><div> Choose File???New Project??? from the main menu.</div>
  34 </li>
  35 <li><div> In the New Project wizard, select the template JME3???Basic Game. Click Next. </div>
  36 <ol>
  37 <li><div> Specify a project name, e.g. &quot;HelloWorldTutorial&quot;</div>
  38 </li>
  39 <li><div> Specify a path where to store your new project, e.g. a <code>jMonkeyProjects</code> directory in your home directory.</div>
  40 </li>
  41 </ol>
  42 </li>
  43 <li><div> Click Finish. </div>
  44 </li>
  45 </ol>
  46
  47 <p>
  48
  49 If you have questions, read more about <a href="/com/jme3/gde/docs/sdk/project_creation.html">Project Creation</a> here.
  50 </p>
  51
  52 <p>
  53 <p><div>We recommend to go through the steps yourself, as described in the tutorials. Alternatively, you can create a project based on the <a href="/com/jme3/gde/docs/sdk/sample_code.html">JmeTests</a> template in the jMonkeyEngine <acronym title="Software Development Kit">SDK</acronym>. It will create a project that already contains the <code>jme3test.helloworld</code> samples (and many others). For example, you can use the JmeTests project to verify whether you got the solution right.
  54 </div></p>
  55 </p>
  56
  57 </div>
  58 <!-- EDIT2 SECTION "Create a Project" [727-1588] -->
  59 <h2><a>Write a SimpleApplication</a></h2>
  60 <div>
  61
  62 <p>
  63
  64 For this tutorial, you want to create a <code>jme3test.helloworld</code> package in your project, and create a file <code>HelloJME3.java</code> in it.
  65 </p>
  66
  67 <p>
  68 In the jMonkeyEngine <acronym title="Software Development Kit">SDK</acronym>:
  69 </p>
  70 <ol>
  71 <li><div> Right-click the Source Packages node of your project.</div>
  72 </li>
  73 <li><div> Choose New??????Java Class to create a new file.</div>
  74 </li>
  75 <li><div> Enter the class name: <code>HelloJME3</code></div>
  76 </li>
  77 <li><div> Enter the package name: <code>jme3test.helloworld</code>. </div>
  78 </li>
  79 <li><div> Click Finish.</div>
  80 </li>
  81 </ol>
  82
  83 <p>
  84 The <acronym title="Software Development Kit">SDK</acronym> creates the file HelloJME3.java for you.
  85 </p>
  86
  87 </div>
  88 <!-- EDIT3 SECTION "Write a SimpleApplication" [1589-2061] -->
  89 <h2><a>Sample Code</a></h2>
  90 <div>
  91
  92 <p>
  93
  94 Replace the contents of the HelloJME3.java file with the following code:
  95 </p>
  96 <pre>package jme3test.helloworld;
  97 &nbsp;
  98 import com.jme3.app.SimpleApplication;
  99 import com.jme3.material.Material;
 100 import com.jme3.math.Vector3f;
 101 import com.jme3.scene.Geometry;
 102 import com.jme3.scene.shape.Box;
 103 import com.jme3.math.ColorRGBA;
 104 &nbsp;
 105 <span>/** Sample 1 - how to get started with the most simple JME 3 application.
 106  * Display a blue 3D cube and view from all sides by
 107  * moving the mouse and pressing the WASD keys. */</span>
 108 public class HelloJME3 extends SimpleApplication &#123;
 109 &nbsp;
 110     public static void main&#40;String&#91;&#93; args&#41;&#123;
 111         HelloJME3 app = new HelloJME3&#40;&#41;;
 112         app.start&#40;&#41;; // start the game
 113     &#125;
 114 &nbsp;
 115     @Override
 116     public void simpleInitApp&#40;&#41; &#123;
 117         Box b = new Box&#40;Vector3f.ZERO, 1, 1, 1&#41;; // create cube shape at the origin
 118         Geometry geom = new Geometry&#40;&quot;Box&quot;, b&#41;;  // create cube geometry from the shape
 119         Material mat = new Material&#40;assetManager,
 120           &quot;Common/MatDefs/Misc/Unshaded.j3md&quot;&#41;;  // create a simple material
 121         mat.setColor&#40;&quot;Color&quot;, ColorRGBA.Blue&#41;;   // set color of material to blue
 122         geom.setMaterial&#40;mat&#41;;                   // set the cube's material
 123         rootNode.attachChild&#40;geom&#41;;              // make the cube appear in the scene
 124     &#125;
 125 &#125;</pre>
 126
 127 <p>
 128 Right-click the HelloJME3 class and choose Run. If a jME3 settings dialog pops up, confirm the default settings.
 129 </p>
 130 <ol>
 131 <li><div> You should see a simple window displaying a 3D cube.</div>
 132 </li>
 133 <li><div> Press the WASD keys and move the mouse to navigate around.</div>
 134 </li>
 135 <li><div> Look at the FPS text and object count information in the bottom left. You will use this information during development, and you will remove it for the release. (To read the numbers correctly, consider that the 14 lines of text counts as 14 objects with 914 vertices.)</div>
 136 </li>
 137 <li><div> Press Escape to close the application.</div>
 138 </li>
 139 </ol>
 140
 141 <p>
 142 Congratulations! Now let&#039;s find out how it works!
 143 </p>
 144
 145 </div>
 146 <!-- EDIT4 SECTION "Sample Code" [2062-3976] -->
 147 <h2><a>Understanding the Code</a></h2>
 148 <div>
 149
 150 <p>
 151
 152 The code above has initialized the scene, and started the application.
 153 </p>
 154
 155 </div>
 156 <!-- EDIT5 SECTION "Understanding the Code" [3977-4084] -->
 157 <h3><a>Start the SimpleApplication</a></h3>
 158 <div>
 159
 160 <p>
 161
 162 Look at the first line. The HelloJME3.java class extends <code>com.jme3.app.SimpleApplication</code>.
 163 </p>
 164 <pre>public class HelloJME3 extends SimpleApplication &#123;
 165   // your code...
 166 &#125;</pre>
 167
 168 <p>
 169 Every JME3 game is an instance of <code>com.jme3.app.SimpleApplication</code>. The SimpleApplication class manages your 3D scene graph and automatically draws it to the screen ??? that is, in short, what a game engine does for you!
 170 </p>
 171
 172 <p>
 173 You start every JME3 game from the main() method, as every standard Java application:
 174 </p>
 175 <ol>
 176 <li><div> Instantiate your <code>SimpleApplication</code>-based class</div>
 177 </li>
 178 <li><div> Call the application&#039;s <code>start()</code> method to start the game engine. </div>
 179 </li>
 180 </ol>
 181 <pre>    public static void main&#40;String&#91;&#93; args&#41;&#123;
 182         HelloJME3 app = new HelloJME3&#40;&#41;; // instantiate the game
 183         app.start&#40;&#41;;                     // start the game!
 184     &#125;</pre>
 185
 186 <p>
 187 This code opens your application window. Let&#039;s learn how you put something into the window next.
 188 </p>
 189
 190 </div>
 191 <!-- EDIT6 SECTION "Start the SimpleApplication" [4085-5044] -->
 192 <h3><a>Understanding the Terminology</a></h3>
 193 <div>
 194 <div><table>
 195         <tr>
 196                 <th>What you want to do</th><th>How you say that in JME3 terminology</th>
 197         </tr>
 198         <tr>
 199                 <td>You want to create a cube.</td><td>I create a Geometry with a 1x1x1 Box shape.</td>
 200         </tr>
 201         <tr>
 202                 <td>You want to use a blue color.</td><td>I create a Material with a blue Color property.</td>
 203         </tr>
 204         <tr>
 205                 <td>You want to colorize the cube blue.</td><td>I set the Material of the Box Geometry.</td>
 206         </tr>
 207         <tr>
 208                 <td>You want to add the cube to the scene.</td><td>I attach the Box Geometry to the rootNode.</td>
 209         </tr>
 210         <tr>
 211                 <td>You want the cube to appear in the center.</td><td>I create the Box at the origin = at <code>Vector3f.ZERO</code>.</td>
 212         </tr>
 213 </table></div>
 214 <!-- EDIT8 TABLE [5086-5559] -->
 215 <p>
 216
 217 If you are unfamiliar with the vocabulary, read more about <a href="/com/jme3/gde/docs/jme3/the_scene_graph.html">the Scene Graph</a> here.
 218 </p>
 219
 220 </div>
 221 <!-- EDIT7 SECTION "Understanding the Terminology" [5045-5652] -->
 222 <h3><a>Initialize the Scene</a></h3>
 223 <div>
 224
 225 <p>
 226
 227 Look at rest of the code sample. The <code>simpleInitApp()</code> method is automatically called once at the beginning when the application starts. Every JME3 game must have this method. In the <code>simpleInitApp()</code> method, you load game objects before the game starts.
 228 </p>
 229 <pre>    public void simpleInitApp&#40;&#41; &#123;
 230        // your initialization code...
 231     &#125;</pre>
 232
 233 <p>
 234 The initialization code of a blue cube looks as follows:
 235 </p>
 236 <pre>    public void simpleInitApp&#40;&#41; &#123;
 237         Box b = new Box&#40;Vector3f.ZERO, 1, 1, 1&#41;; // create a 1x1x1 box shape at the origin
 238         Geometry geom = new Geometry&#40;&quot;Box&quot;, b&#41;;  // create a cube geometry from the box shape
 239         Material mat = new Material&#40;assetManager,
 240           &quot;Common/MatDefs/Misc/Unshaded.j3md&quot;&#41;;  // create a simple material
 241         mat.setColor&#40;&quot;Color&quot;, ColorRGBA.Blue&#41;;   // set color of material to blue
 242         geom.setMaterial&#40;mat&#41;;                   // set the cube geometry 's material
 243         rootNode.attachChild&#40;geom&#41;;              // make the cube geometry appear in the scene
 244     &#125;</pre>
 245
 246 <p>
 247 A typical JME3 game has the following initialization process:
 248 </p>
 249 <ol>
 250 <li><div> You initialize game objects:</div>
 251 <ul>
 252 <li><div> You create or load objects and position them.</div>
 253 </li>
 254 <li><div> You make objects appear in the scene by attaching them to the <code>rootNode</code>.</div>
 255 </li>
 256 <li><div> <strong>Examples:</strong> Load player, terrain, sky, enemies, obstacles, ???, and place them in their start positions.</div>
 257 </li>
 258 </ul>
 259 </li>
 260 <li><div> You initialize variables</div>
 261 <ul>
 262 <li><div> You create variables to track the game state. </div>
 263 </li>
 264 <li><div> You set variables to their start values. </div>
 265 </li>
 266 <li><div> <strong>Examples:</strong> Set the <code>score</code> to 0, set <code>health</code> to 100%, ???</div>
 267 </li>
 268 </ul>
 269 </li>
 270 <li><div> You initialize keys and mouse actions.</div>
 271 <ul>
 272 <li><div> The following input bindings are pre-configured:</div>
 273 <ul>
 274 <li><div> W,A,S,D keys ??? Move around in the scene</div>
 275 </li>
 276 <li><div> Mouse movement and arrow keys ??? Turn the camera</div>
 277 </li>
 278 <li><div> Escape key ??? Quit the game</div>
 279 </li>
 280 </ul>
 281 </li>
 282 <li><div> Define your own additional keys and mouse click actions.</div>
 283 </li>
 284 <li><div> <strong>Examples:</strong> Click to shoot, press Space to jump, ???</div>
 285 </li>
 286 </ul>
 287 </li>
 288 </ol>
 289
 290 </div>
 291 <!-- EDIT9 SECTION "Initialize the Scene" [5653-7652] -->
 292 <h2><a>Conclusion</a></h2>
 293 <div>
 294
 295 <p>
 296
 297 You have learned that a SimpleApplication is a good starting point because it provides you with:
 298 </p>
 299 <ul>
 300 <li><div> A <code>simpleInitApp()</code> method where you create objects.</div>
 301 </li>
 302 <li><div> A <code>rootNode</code> where you attach objects to make them appear in the scene.</div>
 303 </li>
 304 <li><div> Useful default input settings that you can use for navigation in the scene.</div>
 305 </li>
 306 </ul>
 307
 308 <p>
 309
 310 When developing a game application, you want to:
 311 </p>
 312 <ol>
 313 <li><div> Initialize the game scene</div>
 314 </li>
 315 <li><div> Trigger game actions </div>
 316 </li>
 317 <li><div> Respond to user input.</div>
 318 </li>
 319 </ol>
 320
 321 <p>
 322 The now following tutorials teach how you accomplish these tasks with the jMonkeyEngine 3.
 323 </p>
 324
 325 <p>
 326 Continue with the <a href="/com/jme3/gde/docs/jme3/beginner/hello_node.html">Hello Node</a> tutorial, where you learn more details about how to initialize the game world, also known as the scene graph.
 327
 328 </p>
 329 <hr />
 330
 331 <p>
 332 See also:
 333 </p>
 334 <ul>
 335 <li><div> <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer"><param name="content" value="http://jmonkeyengine.org/wiki/doku.php/"><param name="text" value="<html><u>Install the jMonkeyEngine</u></html>"><param name="textColor" value="blue"></object></div>
 336 </li>
 337 <li><div> <a href="/com/jme3/gde/docs/jme3/simpleapplication_from_the_commandline.html">SimpleApplication From the Commandline</a></div>
 338 </li>
 339 <li><div> <a href="/com/jme3/gde/docs/sdk/project_creation.html">Create a JME3 project</a>.</div>
 340 </li>
 341 </ul>
 342 <div><span>
 343         <a href="/wiki/doku.php/tag:beginner?do=showtag&amp;tag=tag%3Abeginner">beginner</a>,
 344         <a href="/wiki/doku.php/tag:intro?do=showtag&amp;tag=tag%3Aintro">intro</a>,
 345         <a href="/wiki/doku.php/tag:documentation?do=showtag&amp;tag=tag%3Adocumentation">documentation</a>,
 346         <a href="/wiki/doku.php/tag:init?do=showtag&amp;tag=tag%3Ainit">init</a>,
 347         <a href="/wiki/doku.php/tag:simpleapplication?do=showtag&amp;tag=tag%3Asimpleapplication">simpleapplication</a>,
 348         <a href="/wiki/doku.php/tag:basegame?do=showtag&amp;tag=tag%3Abasegame">basegame</a>
 349 </span></div>
 350
 351 </div>
 352 <!-- EDIT10 SECTION "Conclusion" [7653-] -->
 353 <p><em><a href="http://hub.jmonkeyengine.org/wiki/doku.php/jme3:beginner:hello_simpleapplication?do=export_xhtmlbody">view online version</a></em></p>