|
@@ -1,6 +1,6 @@
|
|
|
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="Asciidoctor 1.5.4"><title>Custom Controls</title><link rel="stylesheet" href="./asciidoctor.css">
|
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">
|
|
|
-<link rel="stylesheet" href="./coderay-asciidoctor.css"><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css"></head><body class="article toc2 toc-left"><div id="header"><div id="toolbar"><a href="https://github.com/jMonkeyEngine/wiki/edit/master/src/docs/asciidoc/jme3/advanced/custom_controls.adoc"><i class="fa fa-pencil-square" aria-hidden="true"></i></a><a href="https://github.com/jMonkeyEngine/wiki/new/master/src/docs/asciidoc/jme3/advanced/"><i class="fa fa-plus-square" aria-hidden="true"></i></a><input dir="auto" style="position: relative; vertical-align: top;" spellcheck="false" autocomplete="off" class="searchbox__input aa-input" id="doc-search" name="search" placeholder="Search in the doc" required="required" type="search"></div><h1>Custom Controls</h1><div class="details"><span class="author" id="author"></span><br><span id="revnumber">version ,</span> <span id="revdate">2016/03/17 20:48</span></div><div id="toc" class="toc2"><div id="toctitle">Table of Contents</div><ul class="sectlevel1"><li><a href="#usage">Usage</a></li><li><a href="#example-code">Example Code</a></li></ul></div></div><div id="content"><div id="preamble"><div class="sectionbody"><div class="paragraph"><p>A <code>com.jme3.scene.control.Control</code> is a customizable jME3 interface that allows you to cleanly steer the behaviour of game entities (Spatials), such as artificially intelligent behaviour in NPCs, traps, automatic alarms and doors, animals and pets, self-steering vehicles or platforms – anything that moves and interacts. Several instances of custom Controls together implement the behaviours of a type of Spatial.</p></div>
|
|
|
+<link rel="stylesheet" href="./coderay-asciidoctor.css"><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css"></head><body class="article toc2 toc-left"><div id="header"><div id="toolbar"><a href="https://github.com/jMonkeyEngine/wiki/edit/master/src/docs/asciidoc/jme3/advanced/custom_controls.adoc"><i class="fa fa-pencil-square" aria-hidden="true"></i></a><a href="https://github.com/jMonkeyEngine/wiki/new/master/src/docs/asciidoc/jme3/advanced/"><i class="fa fa-plus-square" aria-hidden="true"></i></a><input dir="auto" style="position: relative; vertical-align: top;" spellcheck="false" autocomplete="off" class="searchbox__input aa-input" id="doc-search" name="search" placeholder="Search in the doc" required="required" type="search"></div><h1>Custom Controls</h1><div class="details"><span class="author" id="author"></span><br><span id="revnumber">version ,</span> <span id="revdate">2016/03/17 20:48</span></div><div id="toc" class="toc2"><div id="toctitle">Table of Contents</div><ul class="sectlevel1"><li><a href="#usage">Usage</a></li><li><a href="#example-code">Example Code</a></li><li><a href="#abstractcontrol-class">AbstractControl Class</a></li></ul></div></div><div id="content"><div id="preamble"><div class="sectionbody"><div class="paragraph"><p>A <code>com.jme3.scene.control.Control</code> is a customizable jME3 interface that allows you to cleanly steer the behaviour of game entities (Spatials), such as artificially intelligent behaviour in NPCs, traps, automatic alarms and doors, animals and pets, self-steering vehicles or platforms – anything that moves and interacts. Several instances of custom Controls together implement the behaviours of a type of Spatial.</p></div>
|
|
|
<div class="paragraph"><p>To control global game behaviour see <a href="../../jme3/advanced/application_states.html">Application States</a> – you often use AppStates and Control together.</p></div>
|
|
|
<div class="ulist"><ul><li><p><a href="http://www.youtube.com/watch?v=MNDiZ9YHIpM">Quick video introduction to Custom Controls</a></p></li></ul></div>
|
|
|
<div class="paragraph"><p>To control the behaviour of spatials:</p></div>
|
|
@@ -15,7 +15,75 @@ For example, one NPC can be controlled by a PhysicsControl instance and an AICon
|
|
|
<div class="paragraph"><p>The possibilities are endless. emoji:smiley</p></div></div></div>
|
|
|
<div class="sect1"><h2 id="example-code">Example Code</h2><div class="sectionbody"><div class="paragraph"><p>Other examples include the built-in RigidBodyControl in JME’s physics integration, the built-in TerrainLODControl that updates the terrain’s level of detail depending on the viewer’s perspective, etc.</p></div>
|
|
|
<div class="paragraph"><p>Existing examples in the code base include:</p></div>
|
|
|
-<div class="ulist"><ul><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/animation/AnimControl.java">AnimControl.java</a> allows manipulation of skeletal animation, including blending and multiple channels.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/control/CameraControl.java">CameraControl.java</a> allows you to sync the camera position with the position of a given spatial.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/control/BillboardControl.java">BillboardControl.java</a> displays a flat picture orthogonally, e.g. a speech bubble or informational dialog.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/tree/master/jme3-bullet/src/common/java/com/jme3/bullet/control">PhysicsControl</a> subclasses (such as CharacterControl, RigidBodyControl, VehicleControl) allow you to add physical properties to any spatial. PhysicsControls tie into capabilities provided by the BulletAppState.</p></li></ul></div></div></div></div><div id="footer"><div id="footer-text">Version <br>Last updated 2017-06-22 21:58:56 UTC</div></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script><script>docsearch({
|
|
|
+<div class="ulist"><ul><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/animation/AnimControl.java">AnimControl.java</a> allows manipulation of skeletal animation, including blending and multiple channels.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/control/CameraControl.java">CameraControl.java</a> allows you to sync the camera position with the position of a given spatial.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/control/BillboardControl.java">BillboardControl.java</a> displays a flat picture orthogonally, e.g. a speech bubble or informational dialog.</p></li><li><p><a href="https://github.com/jMonkeyEngine/jmonkeyengine/tree/master/jme3-bullet/src/common/java/com/jme3/bullet/control">PhysicsControl</a> subclasses (such as CharacterControl, RigidBodyControl, VehicleControl) allow you to add physical properties to any spatial. PhysicsControls tie into capabilities provided by the BulletAppState.</p></li></ul></div></div></div>
|
|
|
+<div class="sect1"><h2 id="abstractcontrol-class">AbstractControl Class</h2><div class="sectionbody"><div class="admonitionblock tip"><table><tr><td class="icon"><i class="fa icon-tip" title="Tip"></i></td><td class="content"><div class="paragraph"><p>The most common way to create a Control is to create a class that extends AbstractControl.</p></div></td></tr></table></div>
|
|
|
+<div class="paragraph"><p>The AbstractControl can be found under <code>com.jme3.scene.control.AbstractControl</code>. This is a default abstract class that implements the Control interface.</p></div>
|
|
|
+<div class="ulist"><ul><li><p>You have access to a boolean <code>isEnabled()</code>.</p></li><li><p>You have access to the Spatial object <code>spatial</code>.</p></li><li><p>You override the <code>controlUpdate()</code> method to implement the Spatial’s behaviour.</p></li><li><p>You have access to a <code>setEnabled(boolean)</code> method. This activates or deactivates this Control’s behaviour in this spatial temporarily. While the AbstractControl is toggled to be disabled, the <code>controlUpdate()</code> loop is no longer executed.<br>
|
|
|
+For example, you disable your IdleBehaviourControl when you enable your DefensiveBehaviourControl in a spatial.</p></li></ul></div>
|
|
|
+<div class="paragraph"><p>Usage: Your custom subclass implements the three methods <code>controlUpdate()</code>, <code>controlRender()</code>, <code>setSpatial()</code>, and <code>cloneForSpatial()</code> as shown here:</p></div>
|
|
|
+<div class="listingblock"><div class="content"><pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MyControl</span> <span class="directive">extends</span> AbstractControl <span class="directive">implements</span> Savable, <span class="predefined-type">Cloneable</span> {<span class="error"> </span>
|
|
|
+ <span class="directive">private</span> <span class="type">int</span> index; <span class="comment">// can have custom fields -- example </span>
|
|
|
+
|
|
|
+ <span class="directive">public</span> MyControl(){} <span class="comment">// empty serialization constructor </span>
|
|
|
+
|
|
|
+ <span class="comment">/** Optional custom constructor with arguments that can init custom fields.
|
|
|
+ * Note: you cannot modify the spatial here yet! */</span><span class="error"> </span>
|
|
|
+ <span class="directive">public</span> MyControl(<span class="type">int</span> i){ <span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">// index=i; // example </span>
|
|
|
+ } <span class="error"> </span> <span class="error"> </span>
|
|
|
+
|
|
|
+ <span class="comment">/** This method is called when the control is added to the spatial,
|
|
|
+ * and when the control is removed from the spatial (setting a null value).
|
|
|
+ * It can be used for both initialization and cleanup. */</span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="error"> </span>
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">public</span> <span class="type">void</span> setSpatial(Spatial spatial) {<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="local-variable">super</span>.setSpatial(spatial);<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">/* Example:
|
|
|
+ if (spatial != null){
|
|
|
+ // initialize
|
|
|
+ }else{
|
|
|
+ // cleanup
|
|
|
+ }
|
|
|
+ */</span><span class="error"> </span>
|
|
|
+ }
|
|
|
+<span class="error"> </span>
|
|
|
+ <span class="comment">/** Implement your spatial's behaviour here.
|
|
|
+ * From here you can modify the scene graph and the spatial
|
|
|
+ * (transform them, get and set userdata, etc).
|
|
|
+ * This loop controls the spatial while the Control is enabled. */</span><span class="error"> </span>
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">protected</span> <span class="type">void</span> controlUpdate(<span class="type">float</span> tpf){<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="keyword">if</span>(spatial != <span class="predefined-constant">null</span>) {<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">// spatial.rotate(tpf,tpf,tpf); // example behaviour </span>
|
|
|
+ }<span class="error"> </span>
|
|
|
+ }<span class="error"> </span> <span class="error"> </span>
|
|
|
+
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">public</span> <span class="predefined-type">Control</span> cloneForSpatial(Spatial spatial){<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="directive">final</span> MyControl control = <span class="keyword">new</span> MyControl();<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">/* Optional: use setters to copy userdata into the cloned control */</span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">// control.setIndex(i); // example </span>
|
|
|
+ control.setSpatial(spatial);<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="keyword">return</span> control;<span class="error"> </span>
|
|
|
+ }<span class="error"> </span> <span class="error"> </span>
|
|
|
+
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">protected</span> <span class="type">void</span> controlRender(RenderManager rm, ViewPort vp){<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">/* Optional: rendering manipulation (for advanced users) */</span><span class="error"> </span>
|
|
|
+ }<span class="error"> </span> <span class="error"> </span>
|
|
|
+
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">public</span> <span class="type">void</span> read(JmeImporter im) <span class="directive">throws</span> <span class="exception">IOException</span> {<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="local-variable">super</span>.read(im);<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">// im.getCapsule(this).read(...); </span>
|
|
|
+ }<span class="error"> </span> <span class="error"> </span>
|
|
|
+
|
|
|
+ <span class="annotation">@Override</span><span class="error"> </span>
|
|
|
+ <span class="directive">public</span> <span class="type">void</span> write(JmeExporter ex) <span class="directive">throws</span> <span class="exception">IOException</span> {<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="local-variable">super</span>.write(ex);<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
+ <span class="comment">// ex.getCapsule(this).write(...); </span>
|
|
|
+ }<span class="error"> </span>
|
|
|
+}</code></pre></div></div></div></div></div><div id="footer"><div id="footer-text">Version <br>Last updated 2017-06-22 22:18:16 UTC</div></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script><script>docsearch({
|
|
|
apiKey: 'a736b6d93de805e26ec2f49b55013fbd',
|
|
|
indexName: 'jmonkeyengine',
|
|
|
inputSelector: '#doc-search',
|