|
@@ -4,9 +4,8 @@
|
|
|
<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>
|
|
|
-<div class="olist arabic"><ol class="arabic"><li><p>Create one control for each <em>type of behavior</em>. When you add several controls to one spatial, they will be executed in the order they were added.<br>
|
|
|
-For example, one NPC can be controlled by a PhysicsControl instance and an AIControl instance.</p></li><li><p>Define the custom control and implement its behaviour in the Control’s update method:</p><div class="ulist"><ul><li><p>You can pass arguments into your custom control.</p></li><li><p>In the control class, the object <code>spatial</code> gives you access to the spatial and subspatials that the control is attached to.</p></li><li><p>Here you modify the `spatial’s transformation (move, scale, rotate), play animations, check its environement, define how it acts and reacts.</p></li></ul></div></li><li><p>Add an instance of the Control to a spatial to give it this behavior. The spatial’s game state is updated automatically from now on.<br></p></li></ol></div>
|
|
|
-<div class="listingblock"><div class="content"><pre>spatial.addControl(myControl);</pre></div></div>
|
|
|
+<div class="olist arabic"><ol class="arabic"><li><p>Create one control for each <em>type of behavior</em>. When you add several controls to one spatial, they will be executed in the order they were added.</p><div class="paragraph"><p>For example, one NPC can be controlled by a PhysicsControl instance and an AIControl instance.</p></div></li><li><p>Define the custom control and implement its behaviour in the Control’s update method:</p><div class="ulist"><ul><li><p>You can pass arguments into your custom control.</p></li><li><p>In the control class, the object <code>spatial</code> gives you access to the spatial and subspatials that the control is attached to.</p></li><li><p>Here you modify the <code>spatial’s</code> transformation (move, scale, rotate), play animations, check its environement, define how it acts and reacts.</p></li></ul></div></li><li><p>Add an instance of the Control to a spatial to give it this behavior. The spatial’s game state is updated automatically from now on.</p></li></ol></div>
|
|
|
+<div class="listingblock"><div class="content"><pre class="CodeRay highlight"><code data-lang="java">spatial.addControl(myControl);</code></pre></div></div>
|
|
|
<div class="paragraph"><p>To implement game logic for a type of spatial, you will either extend AbstractControl (most common case), or implement the Control interface, as explained in this article.</p></div></div></div>
|
|
|
<div class="sect1"><h2 id="usage">Usage</h2><div class="sectionbody"><div class="paragraph"><p>Use <a href="../../jme3/advanced/custom_controls.html">Controls</a> to implement the <em>behaviour of types of game entities</em>.</p></div>
|
|
|
<div class="ulist"><ul><li><p>Use Controls to add a type of behaviour (that is, methods and fields) to individual Spatials.</p></li><li><p>Each Control has its own <code>update()</code> loop that hooks into <code>simpleUpdate()</code>. Use Controls to move blocks of code out of the <code>simpleUpdate()</code> loop.</p></li><li><p>One Spatial can be influenced by several Controls. (Very powerful and modular!)</p></li><li><p>Each Spatial needs its own instance of the Control.</p></li><li><p>A Control only has access to and control over the Spatial it is attached to.</p></li><li><p>Controls can be saved as .j3o file together with a Spatial.</p></li></ul></div>
|
|
@@ -18,8 +17,7 @@ For example, one NPC can be controlled by a PhysicsControl instance and an AICon
|
|
|
<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="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.</p><div class="paragraph"><p>For example, you disable your IdleBehaviourControl when you enable your DefensiveBehaviourControl in a spatial.</p></div></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>
|
|
@@ -27,14 +25,16 @@ For example, you disable your IdleBehaviourControl when you enable your Defensiv
|
|
|
<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>
|
|
|
+ * 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>
|
|
|
+ * 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>
|
|
@@ -50,7 +50,8 @@ For example, you disable your IdleBehaviourControl when you enable your Defensiv
|
|
|
<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>
|
|
|
+ * 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>
|
|
@@ -88,9 +89,8 @@ For example, you disable your IdleBehaviourControl when you enable your Defensiv
|
|
|
<div class="ulist"><ul><li><p>To learn more about <code>write()</code> and <code>read()</code>, see <a href="../../jme3/advanced/save_and_load.html">Save and Load</a></p></li><li><p>To learn more about <code>setUserData()</code>, see <a href="../../jme3/advanced/spatial.html">Spatial</a>.</p></li></ul></div></div></div>
|
|
|
<div class="sect1"><h2 id="the-control-interface">The Control Interface</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>In the less common case that you want to create a Control that also extends another class, create a custom interface that extends jME3’s Control interface. Your class can become a Control by implementing the Control interface, and at the same time extending another class.</p></div></td></tr></table></div>
|
|
|
<div class="paragraph"><p>The Control interface can be found under <code>com.jme3.scene.control.Control</code>. It has the following method signatures:</p></div>
|
|
|
-<div class="ulist"><ul><li><p><code>cloneForSpatial(Spatial)</code>: Clones the Control and attaches it to a clone of the given Spatial.<br>
|
|
|
-Implement this method to be able to <a href="../../jme3/advanced/save_and_load.html">save() and load()</a> Spatials carrying this Control.<br>
|
|
|
-The AssetManager also uses this method if the same spatial is loaded twice. You can specify which fields you want your object to reuse (e.g. collisionshapes) in this case.</p></li><li><p><code>setEnabled(boolean)</code>: Toggles a boolean that enables or disables the Control. Goes with accessor <code>isEnabled();</code>. You test for it in the <code>update(float tpf)</code> loop before you execute anything.</p></li><li><p>There are also some internal methods that you do not call from user code: <code>setSpatial(Spatial s)</code>, <code>update(float tpf);</code>, <code>render(RenderManager rm, ViewPort vp)</code>.</p></li></ul></div>
|
|
|
+<div class="ulist"><ul><li><p><code>cloneForSpatial(Spatial)</code>: Clones the Control and attaches it to a clone of the given Spatial.</p><div class="paragraph"><p>Implement this method to be able to <a href="../../jme3/advanced/save_and_load.html">save() and load()</a> Spatials carrying this Control.</p></div>
|
|
|
+<div class="paragraph"><p>The AssetManager also uses this method if the same spatial is loaded twice. You can specify which fields you want your object to reuse (e.g. collisionshapes) in this case.</p></div></li><li><p><code>setEnabled(boolean)</code>: Toggles a boolean that enables or disables the Control. Goes with accessor <code>isEnabled();</code>. You test for it in the <code>update(float tpf)</code> loop before you execute anything.</p></li><li><p>There are also some internal methods that you do not call from user code: <code>setSpatial(Spatial s)</code>, <code>update(float tpf);</code>, <code>render(RenderManager rm, ViewPort vp)</code>.</p></li></ul></div>
|
|
|
<div class="paragraph"><p>Usage example:</p></div>
|
|
|
<div class="olist arabic"><ol class="arabic"><li><p>Create a custom control interface.</p><div class="listingblock"><div class="content"><pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">MyControlInterface</span> <span class="directive">extends</span> <span class="predefined-type">Control</span> {<span class="error"> </span><span class="error"> </span><span class="error"> </span>
|
|
|
<span class="directive">public</span> <span class="type">void</span> setSomething(<span class="type">int</span> x); <span class="comment">// optionally, add custom methods</span>
|
|
@@ -190,7 +190,7 @@ vehicleSpatial.addControl(<span class="keyword">new</span> ManualVehicleControl(
|
|
|
...</code></pre></div></div>
|
|
|
<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>Use the getControl() method on a Spatial to get a specific Control object, and activate its behaviour!</p></div>
|
|
|
<div class="listingblock"><div class="content"><pre class="CodeRay highlight"><code data-lang="java">ManualControl c = mySpatial.getControl(ManualControl.class);
|
|
|
-c.steerX(steerX);</code></pre></div></div></td></tr></table></div></div></div></div><div id="footer"><div id="footer-text">Version <br>Last updated 2018-04-26 20:53:12 +00:00</div></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script><script>docsearch({
|
|
|
+c.steerX(steerX);</code></pre></div></div></td></tr></table></div></div></div></div><div id="footer"><div id="footer-text">Version <br>Last updated 2018-04-28 16:28:49 +00:00</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',
|