asciidoc: add note/important/tip/warning + update source conversion

src/docs/asciidoc/bsd_license.adoc

@@ -9,7 +9,6 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 == jME's BSD License
 
 [source]
-
 ----
 
 Copyright (c) 2003-2016 jMonkeyEngine

src/docs/asciidoc/jm3/solutions.adoc

@@ -27,7 +27,6 @@ First, one must declare another Geometry, for example, a red cube:
 
 
 [source,java]
-
 ----
 
 protected Geometry redCube;
@@ -57,7 +56,6 @@ To have the red cube spin twice as fast as the other cube, simply make it rotate
 
 
 [source,java]
-
 ----
 
 public void simpleUpdate(float tpf) {
@@ -77,7 +75,6 @@ One possible solution is to shrink or grow depending on current size. The cube m
 
 
 [source,java]
-
 ----
 
 private boolean grow = true;
@@ -106,7 +103,6 @@ Another approach is to switch between shrinking and growing every chosen unit of
 
 
 [source,java]
-
 ----
 
 // Time passed
@@ -132,7 +128,6 @@ Another approach is to set the cube scale as the result of a sine wave. This res
 
 
 [source,java]
-
 ----
 
 public void simpleUpdate(float tpf) {
@@ -160,7 +155,6 @@ Same logic! Use a timeVar, and make the Material declaration + initialization li
 
 
 [source,java]
-
 ----
 
 protected Material mat;
@@ -171,7 +165,6 @@ As global var, then the initialization cuts off the Material bit:
 
 
 [source,java]
-
 ----
 
 mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
@@ -182,7 +175,6 @@ And then the simpleUpdate()
 
 
 [source,java]
-
 ----
 
 public void simpleUpdate(float tpf) {
@@ -202,7 +194,6 @@ A possible solution is to change the rotation axis of player from y to x, and ma
 
 
 [source,java]
-
 ----
 
 public void simpleUpdate(float tpf) {
@@ -226,7 +217,6 @@ First, add the mappings for the Up and Down actions to the initKeys() method:
 
 
 [source,java]
-
 ----
 
 private void initKeys() {
@@ -243,7 +233,6 @@ Then implement the actions in the onAnalog() method:
 
 
 [source,java]
-
 ----
 
 public void onAnalog(String name, float value, float tpf) {
@@ -274,7 +263,6 @@ Following the proposed solution 1, add new mappings for the mouse wheel in the i
 
 
 [source,java]
-
 ----
 
 private void initKeys() {
@@ -307,7 +295,6 @@ You can jump right off and obtain the hit object's material, by acessing the “
 
 
 [source,java]
-
 ----
 
 Material g = closest.getGeometry().getMaterial();
@@ -322,7 +309,6 @@ The lines can be added anywhere within the `if (results.size() > 0)` block, a
 
 
 [source,java]
-
 ----
 
 Material material = closest.getGeometry().getMaterial();
@@ -338,7 +324,6 @@ Then, declare a `Spatial golem` variable outside of methods. Then initialize gol
 
 
 [source,java]
-
 ----
 
 golem = assetManager.loadModel("Models/Oto/Oto.mesh.xml");
@@ -349,7 +334,6 @@ Now we need him to show up! So we need to attach him: but the rootNode won't do,
 
 
 [source,java]
-
 ----
 
 shootables.attachChild(golem);
@@ -363,7 +347,6 @@ Here is my code, it works and it is well commented.
 
 
 [source,java]
-
 ----
 
 package jme3test.helloworld;

src/docs/asciidoc/jme3.adoc

@@ -12,7 +12,12 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 The beginner tutorials demonstrate the most common use cases and explain basic concepts. We encourage you to run the sample codes and experiment with them. link:https://github.com/jMonkeyEngine/jmonkeyengine/tree/master/jme3-examples/src/main/java/jme3test[All example code] is included in the jMonkeyEngine SDK: Simply create a new project from the `JmeTests` template. To start writing your own projects, create a new file from the `BasicGame` template.
 
 
-*Press F1*<<sdk#,jMonkeyEngine SDK>>link:https://github.com/jMonkeyEngine/jmonkeyengine[latest development version]
+
+[IMPORTANT]
+====
+*Press F1* in the <<sdk#,jMonkeyEngine SDK>> to browse and search a copy of this wiki's contents while coding. The help documents in the SDK always match the version that you currently use. The wiki is updated for the link:https://github.com/jMonkeyEngine/jmonkeyengine[latest development version] of jME3.
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/3d_models.adoc

@@ -20,7 +20,6 @@ To use 3D models in a jME3 application:
 .  Save the files into a subdirectory of your jME3 project's `assets` directory.
 .  In your code, you use the <<jme3/advanced/asset_manager#,Asset Manager>> to load models as <<jme3/advanced/spatial#,Spatial>>s into a jME application. 
 [source,java]
-
 ----
 Spatial model = assetManager.loadModel(
     "Models/MonkeyHead/MonkeyHead.mesh.xml" );

src/docs/asciidoc/jme3/advanced/animation.adoc

@@ -60,7 +60,6 @@ Create one `com.jme3.animation.AnimControl` object in your JME3 application for
 
 
 [source,java]
-
 ----
 
   AnimControl playerControl; // you need one Control per model
@@ -80,7 +79,6 @@ There often are situations where you want to run several animation sequences at
 
 
 [source,java]
-
 ----
 
   AnimChannel channel_walk = playerControl.createChannel();
@@ -266,7 +264,6 @@ In this short example, we define the space key to trigger playing the “Walk an
 
 
 [source,java]
-
 ----
 
   public void simpleInitApp() {
@@ -296,7 +293,6 @@ A jME3 application that contains animations can implement the `com.jme3.animatio
 
 
 [source,java]
-
 ----
 public class HelloAnimation extends SimpleApplication
                      implements AnimEventListener { ... }
@@ -319,7 +315,6 @@ You have access to the following objects:
 *  The name of the animation that has just finished playing.
 
 [source,java]
-
 ----
 
   public void onAnimCycleDone(AnimControl control, AnimChannel channel, String animName) {
@@ -346,7 +341,6 @@ You have access to the following objects
 *  The name of the animation that will start playing.
 
 [source,java]
-
 ----
 
   public void onAnimChange(AnimControl control, AnimChannel channel, String animName) {

src/docs/asciidoc/jme3/advanced/anisotropic_filtering.adoc

@@ -27,7 +27,6 @@ Example how to set AnisotropicFiltering = 4 for all textures:
 
 
 [source,java]
-
 ----
 
         AssetEventListener asl = new AssetEventListener() {

src/docs/asciidoc/jme3/advanced/application_states.adoc

@@ -50,7 +50,12 @@ Each AppState has its own update loop, which hooks into the main simpleUpdate()
 *  *The AppState has been disabled (paused):* This toggles a boolean isEnabled() to false. Here you switch all objects to their specific “paused behaviour. 
 *  *The AppState is cleaned up:* Here you decide what happens when the AppState is detached. Save this AppState's game state, unregister Controls and InputHandlers, detach related AppStates, detach nodes from the rootNode, etc.
 
-+++<abbr title="Graphical User Interface">GUI</abbr>++++++<abbr title="Graphical User Interface">GUI</abbr>+++
+
+[TIP]
+====
+Tip: AppStates are extremely handy to swap out, or pause/unpause whole sets of other AppStates. For example, an InGameState (loads in-game +++<abbr title="Graphical User Interface">GUI</abbr>+++, activates click-to-shoot input mappings, inits game content, starts game loop) versus MainScreenState (stops game loop, saves and detaches game content, switches to menu screen +++<abbr title="Graphical User Interface">GUI</abbr>+++, switches to click-to-select input mappings).
+====
+
 
 
 
@@ -96,7 +101,6 @@ a|Usage
 a|initialize(asm,app)
 a|When this AppState is added to the game, the RenderThread initializes the AppState and then calls this method. You can modify the scene graph from here (e.g. attach nodes). To get access to the main app, call: 
 [source,java]
-
 ----
 super.initialize(stateManager, app);
 this.app = (SimpleApplication) app;
@@ -141,7 +145,6 @@ Definition:
 
 
 [source,java]
-
 ----
 public class MyAppState extends AbstractAppState {
 
@@ -240,7 +243,6 @@ You can use custom accessors to get data from AppStates, to set data in AppState
 
 
 [source,java]
-
 ----
 this.app.getStateManager().getState(MyAppState.class).doSomeCustomStuffInThisState();
 ----
@@ -252,7 +254,6 @@ To access class fields of the SimpleApplication the way you are used to, initial
 
 
 [source,java]
-
 ----
 
 private SimpleApplication app;

src/docs/asciidoc/jme3/advanced/appstatesdemo.adoc

@@ -8,7 +8,12 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 
 
+[IMPORTANT]
+====
 
+THIS DEMO IS OUT OF DATE AND NEEDS CORRECTING
+
+====
 
 
 
@@ -31,7 +36,6 @@ There are four files, Main.java, GameRunningState.java, StartScreenState.java, S
 == Main.java
 
 [source,java]
-
 ----
 
 package chapter04.appstatedemo;
@@ -132,7 +136,6 @@ public class Main extends SimpleApplication {
 == GameRunningState.java
 
 [source,java]
-
 ----
 
 package chapter04.appstatedemo;
@@ -229,7 +232,6 @@ public class GameRunningState extends AbstractAppState {
 == SettingsScreenState.java
 
 [source,java]
-
 ----
 
 package chapter04.appstatedemo;
@@ -323,7 +325,6 @@ public class SettingsScreenState extends AbstractAppState {
 == StartScreenState.java
 
 [source,java]
-
 ----
 
 package chapter04.appstatedemo;

src/docs/asciidoc/jme3/advanced/asset_manager.adoc

@@ -25,7 +25,6 @@ Advanced users can write a custom build and packaging script, and can register c
 ==== Context
 
 [source]
-
 ----
 
 jMonkeyProjects/MyGame/assets/    # You store assets in subfolders here! <------
@@ -55,7 +54,6 @@ Here is an example how you load assets using the AssetManager. This lines loads
 
 
 [source,java]
-
 ----
 Material mat = (Material) assetManager.loadAsset(
     new AssetKey("Common/Materials/RedColor.j3m"));
@@ -73,14 +71,18 @@ Additionally, you can configure the Asset Manager and add any path to its root.
 By default, jME3 searches for models in a directory named `assets`. 
 
 
-`assets``assets`
+
+[IMPORTANT]
+====
+In Java projects created with the jMonkeyEngine SDK, an `assets` folder is created by default in your project directory. If you are using any other IDE, or the command line, you simply create an `assets` directory manually (see the Codeless Project tip below).
+====
+
 
 
 This is our recommended directory structure for storing assets:
 
 
 [source]
-
 ----
 
 jMonkeyProjects/MyGame/src/...           # Packages, .java source code.
@@ -99,14 +101,24 @@ jMonkeyProjects/MyGame/assets/Textures/    # .jpg, .png; also .mesh.xml+.materia
 These subdirectories are just the most common examples. 
 
 
-`assets`
+
+[IMPORTANT]
+====
+You can rename/delete/add (sub)directories inside the `assets` directory in any way you like. Note however that there is no automatic refactoring for asset paths in the SDK, so if you modify them late in the development process, you have to refactor all paths manually.
+====
+
 
 
 *Examples:* You can rename `assets/Sounds` to `assets/Audio`, you can delete `assets/MatDefs` if you don't use it, you can create `assets/AIscripts`, etc. You can rename/move the `assets/Textures` directory or its subdirectories, but then you have to re-export all models, and re-convert them all to .j3o, so plan ahead!
 
 
-`assets/Textures/``assets/Textures/``assets/Textures`+
-`assets/Models/``assets/Scenes/``assets/Models``assets/Scenes`
+
+[IMPORTANT]
+====
+Store textures in `assets/Textures/` before you work with them in a mesh editor! Export and save 3D model files (.mesh.xml+.material, .mtl+.obj, .blend) into the `assets/Textures/` (!) before you convert the model to binary format (.j3o)! This ensures that texture paths correctly point to the `assets/Textures` directory. +
+After the conversion, you move the .j3o file into the `assets/Models/` or `assets/Scenes/` directories. This way, you can reuse textures, your binaries consistently link the correct textures, and the `assets/Models` and `assets/Scenes` directories don't become cluttered.
+====
+
 
 
 
@@ -116,7 +128,6 @@ Creating a material instance with the definition “Unshaded.j3md:
 
 
 [source,java]
-
 ----
 
 Material mat_brick = new Material( 
@@ -128,7 +139,6 @@ Applying a texture to the material:
 
 
 [source,java]
-
 ----
 
 mat_brick.setTexture("ColorMap", 
@@ -140,7 +150,6 @@ Loading a font:
 
 
 [source,java]
-
 ----
 
 guiFont = assetManager.loadFont("Interface/Fonts/Default.fnt");
@@ -151,7 +160,6 @@ Loading a model:
 
 
 [source,java]
-
 ----
 
 Spatial ninja = assetManager.loadModel("Models/Ninja/Ninja.mesh.xml");
@@ -162,7 +170,6 @@ Loading a scene from an Ogre3D dotScene file stored inside a zip:
 
 
 [source,java]
-
 ----
 
 assetManager.registerLocator("town.zip", ZipLocator.class);
@@ -175,7 +182,6 @@ Alternatively to ZipLocator, there is also a HttpZipLocator that can stream mode
 
 
 [source,java]
-
 ----
 
 assetManager.registerLocator("http://jmonkeyengine.googlecode.com/files/wildhouse.zip", 
@@ -188,7 +194,12 @@ rootNode.attachChild(scene);
 jME3 also offers a ClasspathLocator, ZipLocator, FileLocator, HttpZipLocator, and UrlLocator (see `com.jme3.asset.plugins`). 
 
 
-“
+
+[IMPORTANT]
+====
+The custom build script does not automatically include all ZIP files in the executable build. See “Cannot Locate Resource solution below.
+====
+
 
 
 
@@ -202,14 +213,12 @@ a| Solution!
 a| Load a model with materials 
 a| Use the asset manager's `loadModel()` method and attach the Spatial to the rootNode. 
 [source,java]
-
 ----
 Spatial elephant = assetManager.loadModel("Models/Elephant/Elephant.mesh.xml");
 rootNode.attachChild(elephant);
 ----
 
 [source,java]
-
 ----
 Spatial elephant = assetManager.loadModel("Models/Elephant/Elephant.j3o");
 rootNode.attachChild(elephant);
@@ -219,7 +228,6 @@ rootNode.attachChild(elephant);
 a| Load a model without materials 
 a| If you have a model without materials, you have to add a default material to make it visible. 
 [source,java]
-
 ----
 Spatial teapot = assetManager.loadModel("Models/Teapot/Teapot.obj");
 Material mat = new Material(assetManager, "Common/MatDefs/Misc/ShowNormals.j3md");
@@ -231,7 +239,6 @@ rootNode.attachChild(teapot);
 a| Load a scene 
 a| You load scenes just like you load models: 
 [source,java]
-
 ----
 Spatial scene = assetManager.loadModel("Scenes/house/main.scene");
 rootNode.attachChild(scene);
@@ -250,7 +257,6 @@ My game runs fine when I run it right from the jMonkeyEngine SDK. But when I run
 
 
 [source]
-
 ----
 com.jme3.asset.DesktopAssetManager loadAsset
 WARNING: Cannot locate resource: Scenes/town/main.scene
@@ -283,7 +289,12 @@ Before building the executable, you must use the jMonkeyEngine SDK's context men
 This ensures that the model's Texture paths keep working between your 3D mesh editor and JME3.
 
 
-<<sdk/default_build_script#,default build script>>
+
+[IMPORTANT]
+====
+If you must load custom assets from a non-.j3o ZIP file, you must manually ammend the <<sdk/default_build_script#,default build script>> to copy ZIP files into your distribution. ZIPs are skipped by default.
+====
+
 
 
 
@@ -310,8 +321,18 @@ Store your assets there as described above.
 .  You can now open this (Eclipse or whatever) project in the jMonkeyEngine SDK. +
 Convert assets as described above.
 
-<<jme3/advanced/save_and_load#,BinaryExporter>>
+
+[IMPORTANT]
+====
+If you don't use the SDK for some reason, you can still convert models to j3o format: Load any model in Ogre3D or Wavefront format with the AssetManager.loadModel() as a spatial. Then save the spatial as j3o file using <<jme3/advanced/save_and_load#,BinaryExporter>>.
+====
+
+
 
 
+[TIP]
+====
+Use file version control and let team members check out the project. Your developers open the project in Eclipse (etc) as they are used to. Additionally to their graphic tools, ask your graphic designers to install the jMonkeyEngine SDK, and to check out the codeless project that you just prepared. This makes it easy for non-coding team member to browse and preview game assets, to arrange scenes, and to convert files. At the same time, non-coders don't accidentally mess with code, and developers don't accidentally mess with assets. :)
+====
 
 

src/docs/asciidoc/jme3/advanced/atom_framework.adoc

@@ -20,7 +20,12 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 
 
-<<jme3/atomixtuts#,atomixtuts>>
+[TIP]
+====
+
+Go to the Atomix Game making tutorials. <<jme3/atomixtuts#,atomixtuts>>
+====
+
 
 
 
@@ -146,6 +151,7 @@ Full Features list
 Here are its architecture and components.
 
 
+iframe:http://bubbl.us/view/1860d6/2fd77c/15vOUTXerN5GQ/[width="800px", height="400px", alt="", scroll="true",border="true",align="false"]
 
 
 
@@ -275,11 +281,21 @@ Actually it use directly/indirectly various projects of JME3 great contributors
 *  … other contributors 
 
 ( I will add them later :p please forgive if I can't remember your name immediately )
-…
+
+[WARNING]
+====
+Hundred of opensource projects…Nail it
+====
 
 
+
+
+[TIP]
+====
 _I want to thank all of you for you great great great contributions, help me and my friends here to start learning game programming and doing our own game. Salute! My job is to glue the those great gems together, (pretty time consuming job) :_
 
+====
+
 
 
 As the spliting above, then I will make two different topic to keep them separate, the Atom framework and the Series of game making.

src/docs/asciidoc/jme3/advanced/atom_framework/ai.adoc

@@ -69,7 +69,12 @@ More questions ? Not convinced yet? Go to <<FAQ,FAQ>>
 This Atom AI framework are more or less a “framework to bring AI to jME3 game (also means real-time application)!
 
 
-<<jme3/advanced/atom_framework/ai/researches#,researches>>
+
+[TIP]
+====
+Here is my picked list of <<jme3/advanced/atom_framework/ai/researches#,researches>> and articles you can read in AI field (game and none-game) 
+====
+
 
 
 
@@ -95,8 +100,18 @@ This Atom AI framework are more or less a “framework to bring AI to jME3 game
 
 
 
+[IMPORTANT]
+====
+Note that: despite of the fact, the lib has a lot of dependencies, the author always try have simple fallback - homegrown implemention.  Of course, support a fewer use cases, mainly for specific game genres, but it's better than nothing, that's the bright side 
+====
+
+
 
 
+[IMPORTANT]
+====
+Read alternatives and searches if you want to go further than Atom!
+====
 
 
 
@@ -189,6 +204,7 @@ This Atom AI framework are more or less a “framework to bring AI to jME3 game
 Here are its <<jme3/advanced/atom_framework/ai/architecture/architecture#,Architecture>> and <<jme3/advanced/atom_framework/ai/components/components#,Components>>.
 
 
+iframe:http://bubbl.us/view/1860d6/2fd76d/15vmlQSf.3GMg/[width="98%", height="400px", alt="600px,600px", scroll="true",border="true",align="false"]
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/ai/architecture.adoc

@@ -66,6 +66,11 @@ Logging
 
 
 
+[TIP]
+====
+Javolution, Guava, Guice, Commons Lang, BeanUtils, Math, Logging are a complete sets of libraries for Real-time applications with testable, logable capacities, fullfill each other and has just a little bit overlaps. You can setup them easily via Maven or gradle with JME3.
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/atomcore.adoc

@@ -112,6 +112,11 @@ The game “software should be published in specific enviroment called Context,
 ===== Around Bean
 
 
+[NOTE]
+====
+This is so important to mention that every techs Atom framework are around Bean/ POJO technologies. 
+====
+
 
 
 In <<jme3/advanced/atom_framework/atomcore/beans#,AtomCore Bean>> are leverage in a few ways:
@@ -231,6 +236,11 @@ But, the Manager-Entity system is not forced to be in relationship with each oth
 ===== Component base solution
 
 
+[IMPORTANT]
+====
+We (forum members) and game devs all over the world also have controversial conversations, debates and judgments about it. But I have to admit its an undeniable trend game maker all head into in the next decade as the revolution of GPU, CPU employ data oriented approach and batch processing a lot.
+====
+
 
 
 You can read about Component base solutions and architecture here:
@@ -494,6 +504,11 @@ Collections of userful utilities and datastructures, algorimths here and there.
 
 
 
+[WARNING]
+====
+Note: This package contains a lot of stuff borrowed from libraries and should be clean up. Do not rely too much in this library!
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/atomcore/algorithms.adoc

@@ -202,7 +202,12 @@ So in AtomAA, there is a detection of Recursion and cyclic dependency that can b
 This mean the context of computing is affect the algorithms, lead the algorithm to context-depend. So is it conflict with the definition of algorithm and wrong? Well, in real-life, some algorithms actually work upon a data structure and context, if not to say all of them. The abstraction and agnostic of algorithm is limit but higher than data structure, it just depend in the “context of computing but work in various data structure, even a new one. It's also better than normal datastructure in this “loop situation. You may experience the situation that datastructure implementation may cause infinite loop with them self or others. At least algorithms try to prevent that…
 
 
-*Note:*…
+
+[WARNING]
+====
+*Note:* Actually when the situation happen, there is a way to stop the whole!… but not a clean way to set a flag, clear the flag and continue again, because the next time, the progress can not distingish between the normal processing and the invalid one. At least not a simple way without Tranactional Memeory Model.
+====
+
 
 
 In development mode, with AtomAA , the programmer will be notified and the progress will stop. A monitoring framework can also help. The determistic of the algorithms over arbitrary data (in real-life) is also quite a challange problem. That's also a caveat in AtomAA its self.
@@ -211,7 +216,12 @@ In development mode, with AtomAA , the programmer will be notified and the progr
 
 == Implementation details
 
-*[JavaAA]*
+
+[TIP]
+====
+The *[JavaAA]* (Java Atom Algorithms) tags mark what this package support.
+====
+
 
 
 
@@ -498,6 +508,11 @@ This small library can be used in a wide range of applications especially games
 
 
 
+[TIP]
+====
+Don't limit your imagination
+====
+
 
 
 link:http://en.wikipedia.org/wiki/Algorithmic_game_theory[http://en.wikipedia.org/wiki/Algorithmic_game_theory]

src/docs/asciidoc/jme3/advanced/atom_framework/atomcore/cycle.adoc

@@ -143,6 +143,11 @@ A serial of Tasks can also form atribinary routines ( non-cycle) and be coordina
 
 
 
+[TIP]
+====
+Goto AtomPar for more concurrent/ paralell concepts and advices
+====
+
 
 
 
@@ -185,6 +190,11 @@ The fault torrent architecture of AtomEx make sure some sercurity and transactio
 
 
 
+[TIP]
+====
+Read more about AtomEx for Cloud scale and AtomDust of Mobile scale.
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/atomcore/entitysystem.adoc

@@ -31,6 +31,7 @@ Read: link:http://hub.jmonkeyengine.org/forum/topic/entity-system-topic-united/[
 link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:contributions:entitysystem:detailed[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:contributions:entitysystem:detailed]
 
 
+iframe:https://docs.google.com/presentation/d/1R5ovJi67i9ml6zAcmQPlSe9ZNem1Fuo14hoJZi3iRaY/embed?start=false&loop=false&delayms=3000[width="100%", height="600px", alt="", scroll="true",border="true",align="false"]
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/atomcore/net.adoc

@@ -31,6 +31,7 @@ You can include Optional modules like Kryo (Kryonet), ProtocolBuffer, Zay-ES whi
 
 === Concepts & Papers
 
+iframe:https://docs.google.com/presentation/d/1YxUR8fCc115rkokROZb3GVq1J1vRGnGSlwlu6Q_SB48/embed?start=false&loop=false&delayms=3000[width="100%", height="600px", alt="", scroll="true",border="true",align="false"]
 
 
 
@@ -46,7 +47,6 @@ You can include Optional modules like Kryo (Kryonet), ProtocolBuffer, Zay-ES whi
 ==== A simple network application
 
 [source,java]
-
 ----
 
 class Client implement NetworkService{
@@ -64,7 +64,6 @@ class Client implement NetworkService{
 ----
 
 [source,java]
-
 ----
 
 class Server implement NetworkService{

src/docs/asciidoc/jme3/advanced/atom_framework/atomex.adoc

@@ -15,6 +15,11 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 
 
+[TIP]
+====
+
+It's one of my long-term research, result of more than 6 years of research and 2 years of studying and coding
+====
 
 
 
@@ -63,7 +68,12 @@ ____
 
 ____
 
-link:http://github.com/sgmedia/jme-renderfarm-lite[http://github.com/sgmedia/jme-renderfarm-lite]link:http://github.com/sgmedia/jme-1000loc-mmorpg[http://github.com/sgmedia/jme-1000loc-mmorpg]
+
+[TIP]
+====
+Go try JMERenderFarmLite link:http://github.com/sgmedia/jme-renderfarm-lite[http://github.com/sgmedia/jme-renderfarm-lite] and 1000MMORPG link:http://github.com/sgmedia/jme-1000loc-mmorpg[http://github.com/sgmedia/jme-1000loc-mmorpg] on github
+====
+
 
 
 The most attractive and impressive part is this is not a “config hell framework, somehow Spring-like mechaism, but Convention over configuration…
@@ -159,7 +169,12 @@ Yeah, money somehow..? But Open spirit in its heart!
 
 === Other open-source dependencies
 
-…
+
+[WARNING]
+====
+Hundred of opensource projects…Nail it
+====
+
 
 
 <<jme3/atomixtuts#, Atomix Series of game making>>

src/docs/asciidoc/jme3/advanced/atom_framework/atomexasset.adoc

@@ -35,6 +35,11 @@ In real world, converting-processing data and assets also require amount of time
 
 
 
+[TIP]
+====
+Some of the problems and solutions here can also be applied to other situation and usecaces
+====
+
 
 
 
@@ -103,6 +108,7 @@ Unity: Metadata and SVN integrated
 
 === Slides
 
+iframe:https://docs.google.com/presentation/d/1gvh00FBoSYgvryw7Czbcjxrt5TmlK12P14QRdjKo4NA/embed?start=false&loop=false&delayms=3000[width="100%", height="600px", alt="", scroll="true",border="true",align="false"]
 
 
 
@@ -204,7 +210,12 @@ but the later has extra effects:
 You can see the Atom's asset pipeline as a replacement of the official one. In fact, you can also let them work together seamlessly because Atom pipeline just bypass JME3's assetManager in a few special case.
 
 
-“
+
+[WARNING]
+====
+Remember Atom's asset pipeline is better for “not-well formed assets. In normal situation, you can use JME3's asset without a doubt!
+====
+
 
 
 Way1 - Atom over JME3: Put assetManager under an entry point, let call it “SEP - StaticEntryPoint.

src/docs/asciidoc/jme3/advanced/atom_framework/atomscripting.adoc

@@ -28,6 +28,7 @@ Java has its quirk, the others JVM language try to fullfill it!
 
 ==== NEED OF POWERFUL SCRIPTING SYSTEM
 
+iframe:https://docs.google.com/presentation/d/1Kc1ehI1qLbtEGe-6-q8NikY7Q77A6jvozDaX94BqX0g/embed?start=false&loop=false&delayms=3000[width="100%", height="600px", alt="", scroll="true",border="true",align="false"]
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/cc.adoc

@@ -13,7 +13,12 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 This is an introduction of Character customization tool of Atom framework
 
 
-<<jme3/advanced/atom_framework/quickstart#,quickstart>>
+
+[TIP]
+====
+Go to <<jme3/advanced/atom_framework/quickstart#,quickstart>> if you on a rush!
+====
+
 
 
 
@@ -43,9 +48,19 @@ So to reduce a very big workload of data and assets need for a game with vast da
 *  As close as seen in current AAA games, open to MMORPG and social games.
 
 
+[IMPORTANT]
+====
+Go to alternatives and researches if you want to go further than Atom!
+====
+
+
+
 
+[TIP]
+====
+Try some example in Football game's character cusomization <<jme3/atomixtuts/kickgame/cc#,cc>>
+====
 
-<<jme3/atomixtuts/kickgame/cc#,cc>>
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/codegen.adoc

@@ -140,7 +140,12 @@ link:http://metawidget.sourceforge.net/doc/reference/en/html/ch02.html[http://me
 link:http://metawidget.sourceforge.net/elevator.php[http://metawidget.sourceforge.net/elevator.php]
 
 
-“
+
+[TIP]
+====
+MORAL: Object has “similar semantic with its UI. A thing has conceptal similarties with its representation, if there is a projection from it to the representation.
+====
+
 
 
 
@@ -150,6 +155,11 @@ link:http://wiki.eclipse.org/index.php/EMF/FAQ[http://wiki.eclipse.org/index.php
 
 
 
+[TIP]
+====
+MORAL: 
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/design.adoc

@@ -143,6 +143,11 @@ In Java, a lot good opensource projects are already provide solutions for variou
 
 
 
+[WARNING]
+====
+Hundred of opensource projects…
+====
+
 
 
 For example, AtomCore module depends in these high quality libraries:
@@ -280,6 +285,11 @@ At some point, we have to find a solution to reduce “manual Data + code making
 ==== Around Bean
 
 
+[NOTE]
+====
+This is so important to mention that every techs Atom framework are around Bean/ POJO technologies. 
+====
+
 For example:
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/design/patterns.adoc

@@ -11,7 +11,12 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 == [Focus in] Design patterns and paradigms
 
 This page is about design patterns, programming paradigms in game developing and those supported in AtomCore.
-*NOT**very good*
+
+[WARNING]
+====
+This is *NOT* 1st Computer science class!! Understanding programming paradigms and patterns are very important to who want to do game programming, espeacially in Atom framework; which require *very good* knowledge of paradigms and patterns!
+====
+
 
 
 
@@ -50,7 +55,12 @@ builds upon the strengths of Java but has additional power features inspired by
 link:http://groovy.codehaus.org/[http://groovy.codehaus.org/]
 
 
-link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting]
+
+[TIP]
+====
+Learn groovy: link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting]
+====
+
 
 
 
@@ -151,6 +161,11 @@ also for a game, apply MPV is quite annoying and also tricky!
 
 
 
+[TIP]
+====
+Here is the twist: Actually in JME3, you are doing both, that’s why it look like MVP!
+====
+
 
 
 because of this cycle 

src/docs/asciidoc/jme3/advanced/atom_framework/docs.adoc

@@ -46,6 +46,11 @@ Design & Architecture documentation page:
 == The Code
 
 
+[IMPORTANT]
+====
+Make sure that you've read and understanded Atom's Design part
+====
+
 
 
 
@@ -152,6 +157,11 @@ Some optional groovy facilities are also included (gpars, ASM, ANTLR…)
 
 
 
+[IMPORTANT]
+====
+But note that AtomCore is not depend in Groovy.
+====
+
 
 
 You can also do scripting in other Java scripting frameworks like BeanScript or JavaScript.

src/docs/asciidoc/jme3/advanced/atom_framework/facial.adoc

@@ -34,7 +34,12 @@ Let see how can we do it in JME3, shall we?
 *  Rooms for extends and usecases ( changing art-style, more specialize for simulations…) 
 
 
-<<Researches & Papers,alternatives and researches>>
+[IMPORTANT]
+====
+
+Go to <<Researches & Papers,alternatives and researches>> if you want to go further than Atom!
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/fx.adoc

@@ -49,12 +49,22 @@ These all requirements fit to an DSL, functional and lazy like groovy scenario,
 
 link:http://code.google.com/p/guava-libraries/wiki/FunctionalExplained[http://code.google.com/p/guava-libraries/wiki/FunctionalExplained]
 
+[IMPORTANT]
+====
+This framework's feature goes in two branches: in Java 1.5+ with Guava and in Groovy2+ , the difference will be distinguish later!
+====
+
 
 
 
 ==== Focus in effects
 
 
+[IMPORTANT]
+====
+The abstract concept and even implementation of the Fx framework make it look similar or even exactly like Codegen - the Atom's code generation framework. Because they both lend them selfs from same underlying concepts. But remember Fx is for effects and not focus in the code side. It was born to help people like artist to survive their career without reading more programmin books!!
+====
+
 
 
 Of course we not going to do a whole language enhancement here but use a functional ultilities to get start up quick and go straight to the “real-time effects part later. But remember the base concepts of it, which really to be extend and custom for your own needs. 
@@ -194,7 +204,12 @@ IValueProvider
 
 == Effects
 
-…
+
+[NOTE]
+====
+Ideas from Adobe After effect ,3DSMax, Cinema4D, Processing, Blender…!
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/atom_framework/mmorpgtools.adoc

@@ -72,7 +72,17 @@ Read the full article in researches about the open-source and commercial tool fo
 
 === Techniques
 
-…
+
+[WARNING]
+====
+Warning: hundreds of open-source project. Nail it…
+====
+
+
+[IMPORTANT]
+====
+Go to alternatives and researches if you want to go further than Atom!
+====
 
 
 

src/docs/asciidoc/jme3/advanced/audio.adoc

@@ -27,7 +27,6 @@ The main jME audio class to look at is `com.jme3.audio.AudioNode`. When creating
 
 *  *Buffered:* By default, a new audio node is buffered. This means jME3 loads the whole file into memory before playing. Use this for short sounds. You create a buffered sound  by setting DataType.Buffer, or using no DataType at all: 
 [source,java]
-
 ----
 AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav");
 AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav", DataType.Buffer);
@@ -35,7 +34,6 @@ AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav", DataType.Buffer);
 
 *  *Streamed:* If it is a long file such as music or a dialog, you stream the audio. Streaming means, you load and play in parallel until the sound is done. You cannot loop streams. You create a streamed sound by setting the boolean to true:
 [source,java]
-
 ----
 AudioNode music = new AudioNode(assetManager, "Sound/music.wav", DataType.Stream);
 ----
@@ -126,7 +124,12 @@ a|Reverb is a 3D echo effect that only makes sense with positional AudioNodes. U
 
 |===
 
-`AudioListener`
+
+[IMPORTANT]
+====
+Positional 3D sounds require an `AudioListener` object in the scene (representing the player's ears).
+====
+
 
 
 
@@ -148,6 +151,11 @@ a|Set the angle in degrees for the directional audio. The angle is relative to t
 |===
 
 
+[IMPORTANT]
+====
+Directional 3D sounds require an AudioListener object in the scene (representing the player's ears). 
+====
+
 
 
 
@@ -157,19 +165,16 @@ You play, pause, and stop a node called myAudioNode by using the respective of t
 
 
 [source,java]
-
 ----
 myAudioNode.play();
 ----
 
 [source,java]
-
 ----
 myAudioNode.pause();
 ----
 
 [source,java]
-
 ----
 myAudioNode.stop();
 ----
@@ -181,7 +186,6 @@ You can also start playing instances of an AudioNode. Use the `playInstance()` m
 
 
 [source,java]
-
 ----
 myAudioNode.playInstance();
 ----
@@ -193,7 +197,6 @@ The default AudioListener object `listener` in `SimpleApplication` is the user's
 
 
 [source,java]
-
 ----
 
   @Override
@@ -290,14 +293,12 @@ a|0.0006f
 .  Activate a Environment preset
 **  Either use a default, e.g. make you scene sounds like a dungeon environment: 
 [source,java]
-
 ----
 audioRenderer.setEnvironment(new Environment(Environment.Dungeon));
 ----
 
 **  Or activate <<jme3/advanced/audio_environment_presets#,custom environment settings>> in the Environment constructor:
 [source,java]
-
 ----
 audioRenderer.setEnvironment(
         new Environment( density, diffusion, gain, gainHf, decayTime, decayHf,
@@ -307,18 +308,27 @@ audioRenderer.setEnvironment(
 
 .  Activate 3D audio for certain sounds: 
 [source,java]
-
 ----
 footstepsAudio.setPositional(true);
 footstepsAudio.setReverbEnabled(true);
 ----
 
 
-`com.​jme3.​audio.Environment`…<<jme3/advanced/audio_environment_presets#,examples of custom audio environment presets>>
+
+[TIP]
+====
+A sound engineer can create a custom `com.​jme3.​audio.Environment` object and specify custom environment values such as density, diffusion, gain, decay, delay… You can find many <<jme3/advanced/audio_environment_presets#,examples of custom audio environment presets>> here.
+====
+
 
 
 Advanced users find more info about OpenAL and its features here: link:http://web.archive.org/web/20130327063429/http://connect.creativelabs.com/openal/Documentation/OpenAL_Programmers_Guide.pdf[OpenAL 1.1 Specification]. 
 
 
-`OpenAL EFX not available! Audio effects won't work.`
+
+[IMPORTANT]
+====
+It depends on the hardware whether audio effects are supported (if not, you get the message `OpenAL EFX not available! Audio effects won't work.`)
+====
+
 

src/docs/asciidoc/jme3/advanced/audio_environment_presets.adoc

@@ -14,7 +14,6 @@ Usage:
 
 
 [source,java]
-
 ----
 
 Environment Generic = new Environment(
@@ -29,7 +28,6 @@ audioRenderer.setEnvironment(myEnvironment);
 == Castle
 
 [source,java]
-
 ----
 
 CastleSmallRoom    = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -800, -2000, 1.22f, 0.83f, 0.31f, -100, 0.022f, 0f, 0f, 0f, 600, 0.011f, 0f, 0f, 0f, 0.138f, 0.080f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
@@ -48,7 +46,6 @@ CastleAlcove       = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -60
 == Warehouse, Factory
 
 [source,java]
-
 ----
 
 FactoryAlcove       = new Environment ( new float[]{ 26, 1.8f, 0.590f, -1200, -200, -600, 3.14f, 0.65f, 1.31f, 300, 0.010f, 0f, 0f, 0f, 000, 0.038f, 0f, 0f, 0f, 0.114f, 0.100f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
@@ -67,7 +64,6 @@ FactorySmallroom    = new Environment ( new float[]{ 26, 1.8f, 0.820f, -1000, -2
 == Ice Palace
 
 [source,java]
-
 ----
 
 IcepalaceAlcove       = new Environment ( new float[]{ 26, 2.7f, 0.840f, -1000, -500, -1100, 2.76f, 1.46f, 0.28f, 100, 0.010f, 0f, 0f, 0f, -100, 0.030f, 0f, 0f, 0f, 0.161f, 0.090f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
@@ -86,7 +82,6 @@ IcepalaceSmallroom    = new Environment ( new float[]{ 26, 2.7f, 0.840f, -1000,
 == Space Station
 
 [source,java]
-
 ----
 
 SpacestationAlcove       = new Environment ( new float[]{ 26, 1.5f, 0.780f, -1000, -300, -100, 1.16f, 0.81f, 0.55f, 300, 0.007f, 0f, 0f, 0f, 000, 0.018f, 0f, 0f, 0f, 0.192f, 0.210f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
@@ -104,7 +99,6 @@ SpacestationSmallroom    = new Environment ( new float[]{ 26, 1.5f, 0.700f, -100
 == Wooden Hut or Ship
 
 [source,java]
-
 ----
 
 WoodenAlcove           = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -1800, -1000, 1.22f, 0.62f, 0.91f, 100, 0.012f, 0f, 0f, 0f, -300, 0.024f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
@@ -123,7 +117,6 @@ WoodenCourtyard        = new Environment ( new float[]{ 26, 7.5f, 0.650f, -1000,
 == Sport
 
 [source,java]
-
 ----
 
 SportEmptystadium      = new Environment ( new float[]{ 26, 7.2f, 1f, -1000, -700, -200, 6.26f, 0.51f, 1.10f, -2400, 0.183f, 0f, 0f, 0f, -800, 0.038f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x20} );
@@ -139,7 +132,6 @@ SportFullstadium       = new Environment ( new float[]{ 26, 7.2f, 1f, -1000, -23
 == Pipes
 
 [source,java]
-
 ----
 
 Sewerpipe    = new Environment ( new float[]{ 21, 1.7f, 0.800f, -1000, -1000, 0, 2.81f, 0.14f, 1f, 429, 0.014f, 0f, 0f, 0f, 1023, 0.021f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
@@ -154,7 +146,6 @@ PipeResonant = new Environment ( new float[]{ 26, 1.3f, 0.910f, -1000, -700, -11
 == Moods
 
 [source,java]
-
 ----
 
 Heaven    = new Environment ( new float[]{ 26, 19.6f, 0.940f, -1000, -200, -700, 5.04f, 1.12f, 0.56f, -1230, 0.020f, 0f, 0f, 0f, 200, 0.029f, 0f, 0f, 0f, 0.250f, 0.080f, 2.742f, 0.050f, -2f, 5000f, 250f, 0f, 0x3f} );
@@ -170,7 +161,6 @@ Psychotic = new Environment ( new float[]{ 25, 1f, 0.500f, -1000, -151, 0, 7.56f
 == Car Racing
 
 [source,java]
-
 ----
 
 DrivingCommentator    = new Environment ( new float[]{ 26, 3f, 0f, 1000, -500, -600, 2.42f, 0.88f, 0.68f, -1400, 0.093f, 0f, 0f, 0f, -1200, 0.017f, 0f, 0f, 0f, 0.250f, 1f, 0.250f, 0f, -10f, 5000f, 250f, 0f, 0x20} );
@@ -188,7 +178,6 @@ DrivingTunnel          = new Environment ( new float[]{ 26, 3.1f, 0.810f, -1000,
 == City
 
 [source,java]
-
 ----
 
 CityIndoors   = new Environment ( new float[]{ 16, 7.5f, 0.500f, -1000, -800, 0, 1.49f, 0.67f, 1f, -2273, 0.007f, 0f, 0f, 0f, -1691, 0.011f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
@@ -205,7 +194,6 @@ CityAbandoned = new Environment ( new float[]{ 26, 3f, 0.690f, -1000, -200, -100
 == Small Indoor Rooms
 
 [source,java]
-
 ----
 
 Room         = new Environment ( new float[]{ 2, 1.9f, 1f, -1000, -454, 0, 0.40f, 0.83f, 1f, -1646, 0.002f, 0f, 0f, 0f, 53, 0.003f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
@@ -219,7 +207,6 @@ Stoneroom    = new Environment ( new float[]{ 5, 11.6f, 1f, -1000, -300, 0, 2.31
 == Medium-Sized Indoor Rooms
 
 [source,java]
-
 ----
 
 Workshop     = new Environment ( new float[]{ 26, 1.9f, 1f, -1000, -1700, -800, 0.76f, 1f, 1f, 0, 0.012f, 0f, 0f, 0f, 100, 0.012f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x0} );
@@ -236,7 +223,6 @@ Chapel       = new Environment ( new float[]{ 26, 19.6f, 0.840f, -1000, -500, 0,
 == Large Indoor Rooms
 
 [source,java]
-
 ----
 
 Auditorium     = new Environment ( new float[]{ 6, 21.6f, 1f, -1000, -476, 0, 4.32f, 0.59f, 1f, -789, 0.020f, 0f, 0f, 0f, -289, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
@@ -253,7 +239,6 @@ DomeSaintPauls = new Environment ( new float[]{ 26, 50.3f, 0.870f, -1000, -900,
 == Hallways, Alleys
 
 [source,java]
-
 ----
 
 Carpettedhallway = new Environment ( new float[]{ 11, 1.9f, 1f, -1000, -4000, 0, 0.30f, 0.10f, 1f, -1831, 0.002f, 0f, 0f, 0f, -1630, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
@@ -267,7 +252,6 @@ Alley            = new Environment ( new float[]{ 14, 7.5f, 0.300f, -1000, -270,
 == Outdoors
 
 [source,java]
-
 ----
 
 Backyard      = new Environment ( new float[]{ 26, 80.3f, 0.450f, -1000, -1200, -600, 1.12f, 0.34f, 0.46f, -700, 0.069f, 0f, 0f, -0f, -300, 0.023f, 0f, 0f, 0f, 0.218f, 0.340f, 0.250f, 0f, -5f, 4399.1f, 242.9f, 0f, 0x0} );
@@ -287,7 +271,6 @@ Parkinglot    = new Environment ( new float[]{ 20, 8.3f, 1f, -1000, 0, 0, 1.65f,
 == Water
 
 [source,java]
-
 ----
 
 Underwater     = new Environment ( new float[]{ 22, 1.8f, 1f, -1000, -4000, 0, 1.49f, 0.10f, 1f, -449, 0.007f, 0f, 0f, 0f, 1700, 0.011f, 0f, 0f, 0f, 0.250f, 0f, 1.180f, 0.348f, -5f, 5000f, 250f, 0f, 0x3f} );

src/docs/asciidoc/jme3/advanced/bloom_and_glow.adoc

@@ -26,7 +26,6 @@ image:jme3/advanced/nobloomsky.png[No bloom,with="",height=""]image:jme3/advance
 .  Add the processor to the viewPort
 
 [source,java]
-
 ----
 
  FilterPostProcessor fpp=new FilterPostProcessor(assetManager);
@@ -94,7 +93,6 @@ The tank material looks like this :
 
 
 [source]
-
 ----
 
 Material My Material : Common/MatDefs/Light/Lighting.j3md {
@@ -125,7 +123,6 @@ The glow map is defined here : *GlowMap : Models/HoverTank/tank_glow_map_highres
 .  Add the processor to the viewPort
 
 [source]
-
 ----
 
   FilterPostProcessor fpp=new FilterPostProcessor(assetManager);
@@ -157,7 +154,6 @@ In this case you'll need to use the glow color parameter.
 .  Add the processor to the viewPort
 
 [source]
-
 ----
 
     Material mat = new Material(getAssetManager(), "Common/MatDefs/Misc/SolidColor.j3md");
@@ -192,7 +188,6 @@ You can reduce the size of the bloom sampling just by using the setDownSamplingF
 
 
 [source,java]
-
 ----
 
  BloomFilter bloom=new BloomFilter();
@@ -212,7 +207,6 @@ You can use only one bloom filter for both effects like that
 
 
 [source,java]
-
 ----
 
 BloomFilter bloom=new BloomFilter(BloomFilter.GlowMode.SceneAndObjects);
@@ -230,7 +224,6 @@ In your material definition you need to add those lines in the MaterialParameter
 
 
 [source]
-
 ----
 
  MaterialParameters {
@@ -249,7 +242,6 @@ Then add the following technique :
 
 
 [source]
-
 ----
 
     Technique Glow {
@@ -281,7 +273,6 @@ If you are using a glow map, remove the texture from the material.
 
 
 [source]
-
 ----
 
 material.clearTextureParam("GlowMap");
@@ -292,7 +283,6 @@ If you are using a glow color, set it to black
 
 
 [source]
-
 ----
 
 material.setColor("GlowColor",ColorRGBA.Black);

src/docs/asciidoc/jme3/advanced/building_recast.adoc

@@ -68,7 +68,6 @@ Example of method in wrapper:
 
 
 [source,java]
-
 ----
 
 SWIGEXPORT jint JNICALL Java_com_jme3_ai_navigation_utils_RecastJNI_rcIntArray_1size(JNIEnv *jenv, jclass jcls, jlong jarg1, jobject jarg1_) {
@@ -94,7 +93,6 @@ The following script was used for generating wrapper:
 
 
 [source]
-
 ----
 
 %module Recast

src/docs/asciidoc/jme3/advanced/bullet_multithreading.adoc

@@ -21,7 +21,6 @@ A SimpleApplication with a BulletAppState allows setting the threading type via
 
 
 [source]
-
 ----
 setThreadingType(ThreadingType type);
 ----
@@ -33,7 +32,6 @@ You can activate PARALLEL threading in the simpleInitApp() method:
 
 
 [source,java]
-
 ----
 bulletAppState = new BulletAppState();
 bulletAppState.setThreadingType(BulletAppState.ThreadingType.PARALLEL);
@@ -57,4 +55,9 @@ a|Physics Debug View is rendered accurately.
 |===
 
 
+[TIP]
+====
+You can add more physics spaces by using multiple PARALLEL bulletAppStates. You would do that if you have sets physical objects that never collide (for example, underground bolders and flying cannon balls above ground), so you put those into separate physics spaces, which improves performances (less collisions to check!). 
+====
+
 

src/docs/asciidoc/jme3/advanced/camera.adoc

@@ -89,7 +89,6 @@ The `flyCam` class field gives you access to an AppState that extends the defaul
 
 
 [source]
-
 ----
 
 Q  W             up   forw
@@ -127,7 +126,6 @@ jME3 also supports an optional Chase Cam that can follow a moving target Spatial
 
 
 [source,java]
-
 ----
 
 flyCam.setEnabled(false);

src/docs/asciidoc/jme3/advanced/capture_audio_video_to_a_file.adoc

@@ -17,7 +17,12 @@ from the game while it is running using VideoRecorderAppState.
 
 
 
+[TIP]
+====
+Combine this method with jMonkeyEngine's 
 <<jme3/advanced/cinematics#,Cinematics>>
+feature to record high-quality game trailers!
+====
 
 
 
@@ -33,7 +38,6 @@ Add the following code to your `simpleInitApp()` method.
 
 
 [source,java]
-
 ----
 
 stateManager.attach(new VideoRecorderAppState()); //start recording
@@ -57,10 +61,15 @@ That's all!
 == Advanced Way
 
 
+[NOTE]
+====
+This way of A/V recording is still in development.  
+It works for all of jMonkeyEngine's test cases. 
+If you experience any problems or
+if something isn't clear, please link:http://jmonkeyengine.org/members/bortreb/[let me know]. – bortreb
+====
 
 
-link:http://jmonkeyengine.org/members/bortreb/[let me know]–
-
 
 If you want to record audio as well, record at different framerates,
 or record from multiple viewpoints at once, then there's a full
@@ -92,7 +101,6 @@ The steps are:
 
 
 [source,java]
-
 ----
 
 yourApp.setTimer(new IsoTimer(desiredFramesPerSecond));
@@ -107,7 +115,6 @@ sychronized and will run at exactly the fps which you specified.
 
 
 [source,java]
-
 ----
 
 captureVideo(yourApp, targetVideoFile);
@@ -160,7 +167,6 @@ from one of jMonkeyEngine3's advanced demo applications.
 
 
 [source,java]
-
 ----
 
 import java.io.File;
@@ -262,7 +268,6 @@ distribution.
 
 
 [source,java]
-
 ----
 
 package com.aurellem.capture.examples;

src/docs/asciidoc/jme3/advanced/cinematics.adoc

@@ -35,7 +35,6 @@ A Cinematic is like a movie script for a node.
 
 
 [source,java]
-
 ----
 Cinematic cinematic = new Cinematic(sceneNode, duration);
 cinematic.addCinematicEvent(starttime1, event1);
@@ -112,7 +111,6 @@ A MotionEvent moves a Spatial along a complex path.
 
 
 [source,java]
-
 ----
 MotionEvent events= new MotionEvent (thingNode, path);
 ----
@@ -172,7 +170,6 @@ A SoundEventplays a sound as part of the cinematic.
 
 
 [source,java]
-
 ----
 SoundEvent( audioPath, isStream, duration, loopMode )
 ----
@@ -192,7 +189,6 @@ A GuiEventshows or hide a NiftyGUI as part of a cinematic.
 
 
 [source,java]
-
 ----
 GuiEvent( screen, duration, loopMode )
 ----
@@ -201,7 +197,6 @@ You must use this together with bindUI() to specify the Nifty +++<abbr title="Gr
 
 
 [source,java]
-
 ----
 cinematic.bindUi("Interface/subtitle.xml");
 ----
@@ -220,7 +215,6 @@ An AnimationEvent triggers an animation as part of a cinematic.
 
 
 [source,java]
-
 ----
 AnimationEvent( thingNode, animationName, duration, loopMode )
 ----
@@ -243,7 +237,6 @@ First you have to bind a camera to the cinematic with a unique name. You'll be p
 
 
 [source,java]
-
 ----
 
  CameraNode camNode = cinematic.bindCamera("topView", cam);
@@ -255,7 +248,6 @@ In the above example, I want it to be a top view of the scene looking at the wor
 
 
 [source,java]
-
 ----
 
  //set its position
@@ -269,7 +261,6 @@ Then i just have to schedule its activation in the cinematic. I want it to get a
 
 
 [source,java]
-
 ----
 
  cinematic.activateCamera(3,”topView”);
@@ -292,7 +283,6 @@ You can also create new CinematicEvent by extending link:https://github.com/jMon
 === CinematicEventListener
 
 [source,java]
-
 ----
 CinematicEventListener cel = new CinematicEventListener() {
   public void onPlay(CinematicEvent cinematic) {

src/docs/asciidoc/jme3/advanced/collision_and_intersection.adoc

@@ -83,7 +83,6 @@ The following code snippet can be triggered by listeners (e.g. after an input ac
 
 
 [source,java]
-
 ----
 
   // Calculate detection results
@@ -108,7 +107,6 @@ You can also loop over all results and trigger different reactions depending on
 
 
 [source,java]
-
 ----
 
   // Calculate Results
@@ -157,7 +155,12 @@ image::http://www.jmonkeyengine.com/jme/wiki-data/userref/capsule.png[Capsule,wi
 *  Type.OBB = Oriented bounding box. This bounding box is more precise because it can rotate with its content, but is computationally more expensive. (Currently not supported.)
 *  Type.Capsule = Cylinder with rounded ends, also called “swept sphere. Typically used for mobile characters. (Currently not supported.)
 
-<<jme3/advanced/physics#,CollisionShapes>>
+
+[NOTE]
+====
+Note: If you are looking for bounding volumes for physical objects, use <<jme3/advanced/physics#,CollisionShapes>>.
+====
+
 
 
 
@@ -167,7 +170,6 @@ For example you can use Bounding Volumes on custom meshes, or complex non-physic
 
 
 [source,java]
-
 ----
 mesh.setBound(new BoundingSphere());
 mesh.updateBound();
@@ -191,7 +193,12 @@ Rays are used to perform line-of-sight calculations. This means you can detect w
 *  *Click to select:* You can determine what a user has clicked by casting a ray from the camera forward in the direction of the camera. Now identify the closest collision of the ray with the rootNode, and you have the clicked object.
 *  *Line of sight:* Cast a ray from a player in the direction of another player. Then you detect all collisions of this ray with other entities (walls versus foliage versus window panes) and use this to calculate how likely it is that one can see the other.
 
-–
+
+[TIP]
+====
+These simple but powerful ray-surface intersection tests are called Ray Casting. As opposed to the more advanced Ray Tracing technique, Ray Casting does not follow the ray's reflection after the first hit – the ray just goes straight on.
+====
+
 
 
 Learn the details of how to implement <<jme3/advanced/mouse_picking#,Mouse Picking>> here.

src/docs/asciidoc/jme3/advanced/combo_moves.adoc

@@ -42,7 +42,6 @@ For example:
 
 
 [source,java]
-
 ----
 
 inputManager.addMapping("Left",    new KeyTrigger(KeyInput.KEY_LEFT));
@@ -65,7 +64,6 @@ The following example shows how a fireball combo move is triggered by pressing t
 
 
 [source,java]
-
 ----
 
 ComboMove fireball = new ComboMove("Fireball");
@@ -81,7 +79,6 @@ Also create a ComboMoveExecution object for each ComboMove. You need it later to
 
 
 [source,java]
-
 ----
 
 ComboMoveExecution fireballExec = new ComboMoveExecution(fireball);
@@ -162,7 +159,6 @@ We also track the cast time of a combo to determine if it has timed out (see upd
 
 
 [source,java]
-
 ----
 
 private HashSet<String> pressedMappings = new HashSet<String>();
@@ -216,7 +212,6 @@ Now that you have detected the current move, you want to execute it. You do that
 
 
 [source,java]
-
 ----
 
 @Override

src/docs/asciidoc/jme3/advanced/custom_controls.adoc

@@ -27,7 +27,6 @@ For example, one NPC can be controlled by a PhysicsControl instance and an AICon
 
 .  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. 
 [source,java]
-
 ----
 spatial.addControl(myControl);
 ----
@@ -80,6 +79,11 @@ Existing examples in the code base include:
 == AbstractControl Class
 
 
+[TIP]
+====
+The most common way to create a Control is to create a class that extends AbstractControl.
+====
+
 
 
 The AbstractControl can be found under `com.jme3.scene.control.AbstractControl`. This is a default abstract class that implements the Control interface.
@@ -95,7 +99,6 @@ Usage: Your custom subclass implements the three methods `controlUpdate()`, `con
 
 
 [source,java]
-
 ----
 
 public class MyControl extends AbstractControl implements Savable, Cloneable {
@@ -175,6 +178,11 @@ See also:
 == The Control Interface
 
 
+[TIP]
+====
+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.
+====
+
 
 
 The Control interface can be found under `com.jme3.scene.control.Control`. It has the following method signatures:
@@ -191,7 +199,6 @@ Usage example:
 
 
 [source,java]
-
 ----
 public interface MyControlInterface extends Control {
     public void setSomething(int x); // optionally, add custom methods
@@ -202,7 +209,6 @@ public interface MyControlInterface extends Control {
 
 
 [source,java]
-
 ----
 public class MyControl extends MyCustomClass implements MyControlInterface {
 
@@ -280,7 +286,6 @@ Here an example from the link:http://code.google.com/p/monkeyzone/[MonkeyZone] c
 
 
 [source,java]
-
 ----
 
 public class CharacterAnimControl implements Control {
@@ -298,7 +303,6 @@ public class CharacterAnimControl implements Control {
 
 
 [source,java]
-
 ----
 public interface ManualControl extends Control {
     public void steerX(float value);
@@ -314,7 +318,6 @@ Then you create custom sub-Controls and implement the methods accordingly to the
 
 
 [source,java]
-
 ----
 public class ManualVehicleControl   extends ManualControl {...}
 ----
@@ -323,7 +326,6 @@ public class ManualVehicleControl   extends ManualControl {...}
 
 
 [source,java]
-
 ----
 public class ManualCharacterControl extends ManualControl {...}
 ----
@@ -332,7 +334,6 @@ Then add the appropriate controls to spatials:
 
 
 [source,java]
-
 ----
 
 characterSpatial.addControl(new ManualCharacterControl());
@@ -345,7 +346,6 @@ vehicleSpatial.addControl(new ManualVehicleControl());
 
 
 [source,java]
-
 ----
 ManualControl c = mySpatial.getControl(ManualControl.class);
 c.steerX(steerX);

src/docs/asciidoc/jme3/advanced/custom_meshes.adoc

@@ -41,7 +41,6 @@ In this tutorial we want to create a 3x3 Quad. The quad has four vertices, and i
 
 
 [source]
-
 ----
 0,3,0--3,3,0
 | \        |
@@ -59,7 +58,6 @@ The base class for creating meshes is `com.jme3.scene.Mesh`.
 
 
 [source,java]
-
 ----
 Mesh mesh = new Mesh();
 ----
@@ -74,7 +72,6 @@ To define your own shape, determine the shape's *vertex coordinates* in 3D space
 
 
 [source,java]
-
 ----
 
 Vector3f [] vertices = new Vector3f[4];
@@ -92,7 +89,6 @@ Next, we define the Quad's 2D *texture coordinates* for each vertex, in the same
 
 
 [source,java]
-
 ----
 
 Vector2f[] texCoord = new Vector2f[4];
@@ -116,7 +112,6 @@ Remember that you must specify the vertices counter-clockwise.
 
 
 [source,java]
-
 ----
 
 int [] indexes = { 2,0,1, 1,3,2 };
@@ -131,7 +126,6 @@ This syntax means:
 *  The 1,3,2 triangle start at bottom right, continues top right, and ends at top left.
 
 [source]
-
 ----
 
 2\2--3
@@ -144,7 +138,12 @@ This syntax means:
 If the shape is more complex, it has more triangles, and therefor also more vertices/indices. Just continue expanding the list by adding groups of three indices for each triangle. (For example a three-triangle “house shape has 5 vertices/indices and you'd specify three groups: `int [] indexes = { 2,0,1, 1,3,2, 2,3,4 };`.) 
 
 
-<<jme3/advanced/spatial#,Spatial>>`FaceCullMode.Back`“
+
+[TIP]
+====
+If you get the order wrong (clockwise) for some of the triangles, then these triangles face backwards. If the <<jme3/advanced/spatial#,Spatial>>'s material uses the default `FaceCullMode.Back` (see “face culling), the broken triangles appear as holes in the rendered mesh. You need to identify and fix them in your code.
+====
+
 
 
 
@@ -163,7 +162,6 @@ You store the Mesh data in a buffer.
 .  To render the mesh in the scene, we need to pre-calculate the bounding volume of our new mesh: Call the `updateBound()` method on it.
 
 [source,java]
-
 ----
 
 mesh.setBuffer(Type.Position, 3, BufferUtils.createFloatBuffer(vertices));
@@ -183,7 +181,6 @@ We create a `com.jme3.scene.Geometry` and `com.jme3.material.Material`from our `
 
 
 [source,java]
-
 ----
 
 Geometry geo = new Geometry("OurMesh", mesh); // using our custom mesh object
@@ -206,7 +203,6 @@ We created a quad Mesh it can be replace by a Quad such as :
 
 
 [source,java]
-
 ----
 
 Quad quad = new Quad(1,1); // replace the definition of Vertex and Textures Coordinates plus indexes
@@ -223,7 +219,6 @@ If you want to change the Textures Coordinates, in order to change the scale of
 
 
 [source,java]
-
 ----
 
 Quad quad = new Quad(1,1);
@@ -259,7 +254,6 @@ Vertex coloring is a simple way of coloring meshes. Instead of just assigning on
 
 
 [source,java]
-
 ----
 Geometry geo = new Geometry ("ColoredMesh", mesh); // using the custom mesh
 Material matVC = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
@@ -272,7 +266,6 @@ You create a float array color buffer:
 *  Assign 4 color values, RGBA, to each vertex.
 **  To loop over the 4 color values, use a color index 
 [source,java]
-
 ----
 int colorIndex = 0;
 ----
@@ -281,7 +274,6 @@ int colorIndex = 0;
 *  The color buffer contains four color values for each vertex.
 **  The Quad in this example has 4 vertices. 
 [source,java]
-
 ----
 float[] colorArray = new float[4*4];
 
@@ -289,7 +281,6 @@ float[] colorArray = new float[4*4];
 
 **  Tip: If your mesh has a different number of vertices, you would write: 
 [source,java]
-
 ----
 float[] colorArray = new float[yourVertexCount * 4]
 ----
@@ -300,7 +291,6 @@ Loop over the colorArray buffer to quickly set some RGBA value for each vertex.
 
 
 [source,java]
-
 ----
 
 // note: the red and green values are arbitray in this example
@@ -320,7 +310,6 @@ Next, set the color buffer. An RGBA color value contains four float components,
 
 
 [source,java]
-
 ----
 mesh.setBuffer(Type.Color, 4, colorArray);
 geo.setMaterial(matVC);
@@ -337,7 +326,6 @@ The previous examples used the mesh together with the `Unshaded.j3md` material.
 
 
 [source,java]
-
 ----
 
 float[] normals = new float[12];
@@ -359,7 +347,6 @@ Additionally to coloring the faces as just described, you can hide the faces and
 
 
 [source,java]
-
 ----
 Geometry coloredMesh = new Geometry ("ColoredMesh", cMesh);
 ...
@@ -391,14 +378,12 @@ In case however that your usecase requires the backfaces be visible, you have tw
 
 *  If you have a very simple scene, you can simply deactivate backface culling for this one mesh's material. 
 [source]
-
 ----
 mat.getAdditionalRenderState().setFaceCullMode(FaceCullMode.Off);
 ----
 
 *  Another solution for truly double-sided meshes is to specify each triangle twice, the second time with the opposite order of vertices. The second (reversed) triangle is a second frontface that covers up the culled backface. 
 [source]
-
 ----
 int[] indexes = { 2,0,1, 1,3,2, 2,3,1, 1,0,2 };
 ----

src/docs/asciidoc/jme3/advanced/debugging.adoc

@@ -34,7 +34,6 @@ The coordinate axes (com.jme3.scene.debug.Arrow) help you see the cardinal direc
 
 
 [source,java]
-
 ----
 
 private void attachCoordinateAxes(Vector3f pos){
@@ -69,7 +68,6 @@ Use a wireframe grid (com.jme3.scene.debug.Grid) as a ruler or simple floor.
 
 
 [source,java]
-
 ----
 
 private Geometry attachGrid(Vector3f pos, float size, ColorRGBA color){
@@ -91,7 +89,6 @@ Use a wireframe cube (com.jme3.scene.debug.WireBox) as a stand-in object to see
 
 
 [source,java]
-
 ----
 
 public Geometry attachWireBox(Vector3f pos, float size, ColorRGBA color){
@@ -113,7 +110,6 @@ Use a wireframe sphere (com.jme3.scene.debug.WireSphere) as a stand-in object to
 
 
 [source,java]
-
 ----
 
 private Geometry attachWireSphere(Vector3f pos, float size, ColorRGBA color){
@@ -135,7 +131,6 @@ You can display a wireframe of the (usually invisible) collision shape around al
 
 
 [source,java]
-
 ----
 physicsSpace.enableDebug(assetManager);
 ----
@@ -156,7 +151,6 @@ Making the skeleton visible inside animated models can be handy for debugging an
 
 
 [source,java]
-
 ----
 
      SkeletonDebugger skeletonDebug = 
@@ -179,7 +173,6 @@ Then you can add a switch to toggle the model's wireframe on and off, like this:
 
 .  Create a key input trigger that switches between the two materials: E.g. we toggle when the T key is pressed: 
 [source,java]
-
 ----
     inputManager.addMapping("toggle wireframe", new KeyTrigger(KeyInput.KEY_T));
     inputManager.addListener(actionListener, "toggle wireframe");
@@ -187,7 +180,6 @@ Then you can add a switch to toggle the model's wireframe on and off, like this:
 
 .  Now add the toggle action to the action listener 
 [source,java]
-
 ----
 
   private ActionListener actionListener = new ActionListener() {
@@ -205,7 +197,6 @@ Then you can add a switch to toggle the model's wireframe on and off, like this:
 
 .  Alternatively you could traverse over the whole scene and toggle for all Geometry objects in there if you don't want to create a new SceneProcessor 
 [source,java]
-
 ----
 
   private ActionListener actionListener = new ActionListener() {
@@ -239,7 +230,6 @@ To display the wireframe of the entire scene instead on one material at a time,
 
 
 [source,java]
-
 ----
 public class WireProcessor implements SceneProcessor {    
     
@@ -286,7 +276,6 @@ Then attach the scene processor to the +++<abbr title="Graphical User Interface"
 
 
 [source,java]
-
 ----
 getViewPort().addProcessor(new WireProcessor());
 ----

src/docs/asciidoc/jme3/advanced/effects_overview.adoc

@@ -22,7 +22,6 @@ jME3 supports several types of special effects: Post-Processor Filters, ScenePro
 === Particle Emitter
 
 [source,java]
-
 ----
 
 public class MyGame extends SimpleApplication {
@@ -43,7 +42,6 @@ public class MyGame extends SimpleApplication {
 === Scene Processor
 
 [source,java]
-
 ----
 
 public class MyGame extends SimpleApplication {
@@ -61,7 +59,6 @@ public class MyGame extends SimpleApplication {
 === Post-Processor Filter
 
 [source,java]
-
 ----
 
 public class MyGame extends SimpleApplication {

src/docs/asciidoc/jme3/advanced/endless_terraingrid.adoc

@@ -7,7 +7,12 @@
 ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 
-link:http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072[http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072]
+
+[NOTE]
+====
+Deprecated. Look at link:http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072[http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072] instead
+====
+
 
 
 TerrainGrid is DEPRECATED.

src/docs/asciidoc/jme3/advanced/fade.adoc

@@ -21,7 +21,6 @@ The effect uses com.jme3.post.FilterPostProcessor and com.jme3.post.filters.Fade
 .  Add the FilterPostProcessor to the default viewPort.
 
 [source,java]
-
 ----
 
 private FilterPostProcessor fpp;

src/docs/asciidoc/jme3/advanced/headless_server.adoc

@@ -32,7 +32,6 @@ First, let's take a look at the default way of creating a new game (in its simpl
 
 
 [source,java]
-
 ----
 
 public static void main(String[] args) {
@@ -48,7 +47,6 @@ Now, with a simple change you can start your game in Headless mode. This means t
 
 
 [source,java]
-
 ----
 
 import com.jme3.system.JmeContext;

src/docs/asciidoc/jme3/advanced/hinges_and_joints.adoc

@@ -43,7 +43,6 @@ The hookNode is the fixed point from which the pendulum hangs. It has no mass.
 
 
 [source,java]
-
 ----
 
 Node hookNode=PhysicsTestHelper.createPhysicsTestNode(
@@ -65,7 +64,6 @@ The pendulumNode is the dynamic part of the construction. It has a mass.
 
 
 [source,java]
-
 ----
 
 Node pendulumNode=PhysicsTestHelper.createPhysicsTestNode(
@@ -108,7 +106,6 @@ You create the HingeJoint after you have created the nodes that are to be chaine
 
 
 [source,java]
-
 ----
 
 private HingeJoint joint;
@@ -145,7 +142,6 @@ Remember to add all joint objects to the physicsSpace, just like you would do wi
 
 
 [source,java]
-
 ----
 bulletAppState.getPhysicsSpace().add(joint);
 ----
@@ -166,7 +162,6 @@ The method to call on the joint is `enableMotor()`.
 
 
 [source,java]
-
 ----
 joint.enableMotor(true, 1, .1f);
 joint.enableMotor(true, -1, .1f);
@@ -182,7 +177,6 @@ When you disable the motor, the chained nodes are exposed to gravity again:
 
 
 [source,java]
-
 ----
 joint.enableMotor(false, 0, 0);
 ----

src/docs/asciidoc/jme3/advanced/hud.adoc

@@ -71,16 +71,20 @@ This is how you use the guiNode for HUDs:
 The BitmapTexts and Pictures appear as 2 dimensional element on the screen.
 
 
-+++<abbr title="Graphical User Interface">GUI</abbr>+++
 
+[TIP]
+====
+By default, the guiNode has some scene graph statistics attached. To clear the guiNode before you attach your own +++<abbr title="Graphical User Interface">GUI</abbr>+++ elements, use the following methods: 
 
-[source,java]
 
+[source,java]
 ----
 setDisplayStatView(false); setDisplayFps(false);
 ----
 
 
+====
+
 
 
 
@@ -90,7 +94,6 @@ A simple image can be displayed using `com.jme3.ui.Picture`.
 
 
 [source,java]
-
 ----
 Picture pic = new Picture("HUD Picture");
 pic.setImage(assetManager, "Textures/ColoredTex/Monkey.png", true);
@@ -111,7 +114,6 @@ You use `com.jme3.font.BitmapText` to display text on the screen.
 
 
 [source,java]
-
 ----
 
 BitmapText hudText = new BitmapText(guiFont, false);          
@@ -127,7 +129,6 @@ The BitmapFont object `guiFont` is a default font provided by SimpleApplication.
 
 
 [source]
-
 ----
 BitmapFont myFont = assetManager.loadFont("Interface/Fonts/Console.fnt");
 hudText = new BitmapText(myFont, false);
@@ -146,7 +147,12 @@ hudText = new BitmapText(myFont, false);
 It is technically possible to attach Quads and 3D Geometries to the HUD. They show up as flat, static +++<abbr title="Graphical User Interface">GUI</abbr>+++ elements. The size unit for the guiNode is pixels, not world units. If you attach a Geometry that uses a lit Material, you must add a light to the guiNode. 
 
 
-+++<abbr title="Graphical User Interface">GUI</abbr>+++
+
+[IMPORTANT]
+====
+If you don't see an attached object in the +++<abbr title="Graphical User Interface">GUI</abbr>+++, check it's position and material (add a light to guiNode). Also verify whether it is not too tiny to be seen. For comparison: A 1 world-unit wide cube is only 1 pixel wide when attached to the guiNode! You may need to scale it bigger.
+====
+
 
 
 
@@ -156,7 +162,6 @@ Use the update loop to keep the content up-to-date.
 
 
 [source,java]
-
 ----
 public void simpleUpdate(float tpf) {
   ...

src/docs/asciidoc/jme3/advanced/input_handling.adoc

@@ -131,7 +131,6 @@ In your IDE, use code completion to quickly look up Trigger literals. In the jMo
 == 2. Remove Default Trigger Mappings
 
 [source]
-
 ----
 inputManager.deleteMapping( SimpleApplication.INPUT_MAPPING_MEMORY );
 ----
@@ -170,7 +169,6 @@ Give the mapping a meaningful name. The name should reflect the action, not the
 
 
 [source,java]
-
 ----
 
 inputManager.addMapping("Pause Game", new KeyTrigger(KeyInput.KEY_P));
@@ -183,7 +181,6 @@ There are cases where you may want to provide more then one trigger for one acti
 
 
 [source,java]
-
 ----
 
 inputManager.addMapping("Left",  new KeyTrigger(KeyInput.KEY_A), 
@@ -220,7 +217,6 @@ The jME3 input manager supports two types of event listeners for inputs: AnalogL
 *  
 
 [source,java]
-
 ----
 
 private ActionListener actionListener = new ActionListener() {
@@ -246,7 +242,6 @@ private ActionListener actionListener = new ActionListener() {
 
 
 [source,java]
-
 ----
 
 private AnalogListener analogListener = new AnalogListener() {
@@ -266,7 +261,6 @@ In the following example, you register the “Pause Game mapping to the `actionL
 
 
 [source,java]
-
 ----
 inputManager.addListener(actionListener, new String[]{"Pause Game"});
 ----
@@ -275,7 +269,6 @@ In the following example, you register navigational mappings to the `analogListe
 
 
 [source,java]
-
 ----
 inputManager.addListener(analogListener, new String[]{"Left", "Right"});
 ----
@@ -284,6 +277,11 @@ As you see, you can add several listeners in one String array. You can call the
 
 
 
+[TIP]
+====
+Did you register an action, but it does not work? Check the string's capitalization and spelling, it's case sensitive!
+====
+
 
 
 
@@ -305,7 +303,6 @@ In the most common case, you want an action to be triggered once, in the moment
 
 
 [source,java]
-
 ----
 private ActionListener actionListener = new ActionListener() {
     public void onAction(String name, boolean keyPressed, float tpf) {
@@ -328,7 +325,6 @@ The following example shows how you define actions with an AnalogListener. These
 
 
 [source,java]
-
 ----
 private AnalogListener analogListener = new AnalogListener() {
     public void onAnalog(String name, float value, float tpf) {

src/docs/asciidoc/jme3/advanced/j3m_material_files.adoc

@@ -21,7 +21,6 @@ If you want to colorize simple shapes (one texture all around), then .j3m are th
 .  Place the file in your project's `assets/Materials/` directory, e.g. `MyGame/src/assets/Materials/SimpleBump.j3m`
 .  Edit the file and add content using the following Syntax, e.g.:
 [source]
-
 ----
 
 Material shiny bumpy rock : Common/MatDefs/Light/Lighting.j3md {
@@ -51,7 +50,12 @@ How to this file is structured:
 
 .  Check the detailed syntax reference below if you are unsure.
 
-→→→
+
+[TIP]
+====
+In the jMonkeyEngine SDK, use File→New File→Material→Empty Material File to create .j3m files. You can edit .j3m files directly in the SDK. On the other hand, they are plain text files, so you can also create them in any plain text editor.
+====
+
 
 
 
@@ -61,7 +65,6 @@ This is how you use the prepared .j3m Material on a Spatial. Since you have save
 
 
 [source,java]
-
 ----
 myGeometry.setMaterial(assetManager.loadMaterial("Materials/SimpleBump.j3m"));
 ----
@@ -246,7 +249,6 @@ a| Enable point sprite rendering for point meshes
 === Example 1: Shiny
 
 [source,java]
-
 ----
 
 Spatial signpost = (Spatial) assetManager.loadAsset(
@@ -262,7 +264,6 @@ The file `assets/Models/Sign Post/Sign Post.j3m` contains:
 
 
 [source]
-
 ----
 
 Material Signpost : Common/MatDefs/Light/Lighting.j3md {
@@ -287,7 +288,6 @@ The JPG files are in the same directory, `assets/Models/Sign Post/…`.
 === Example 2: Repeating Texture
 
 [source,java]
-
 ----
 
 Material mat = assetManager.loadMaterial(
@@ -302,7 +302,6 @@ The file `assets/Textures/Terrain/Pond/Pond.j3m` contains:
 
 
 [source]
-
 ----
 
 Material Pong Rock : Common/MatDefs/Light/Lighting.j3md {
@@ -325,7 +324,6 @@ The file `assets/Models/Tree/Leaves.j3m` contains:
 
 
 [source]
-
 ----
 
 Material Leaves : Common/MatDefs/Light/Lighting.j3md {

src/docs/asciidoc/jme3/advanced/jme3_shadernodes.adoc

@@ -76,7 +76,6 @@ global structure should look like this :+
 
 
 [source,java]
-
 ----
 
 ShaderNodeDefinitions{
@@ -144,7 +143,6 @@ Here is a typical shader node definition
 
 
 [source,java]
-
 ----
 
 ShaderNodeDefinitions{
@@ -184,7 +182,6 @@ _Example_
 
 
 [source]
-
 ----
 
       float myArray[10]
@@ -204,7 +201,6 @@ _Example_
 
 
 [source]
-
 ----
 
      float myArray[NumberOfElements]
@@ -232,7 +228,6 @@ Here is a the code of the LightMap.frag shader.+
 
 
 [source,java]
-
 ----
 
 void main(){
@@ -259,7 +254,6 @@ Here is how a ShaderNode declaration should look :
 
 
 [source,java]
-
 ----
 
 ShaderNode <ShaderNodeName>{
@@ -293,7 +287,6 @@ ShaderNode <ShaderNodeName>{
 
 
 [source,java]
-
 ----
 
         #if defined(COLOR) || defined(COLORMAP)
@@ -327,10 +320,14 @@ ShaderNode <ShaderNodeName>{
 
 Here is an example of a very simple Material definition that just displays a solid color (controlled by a material parameter) on a mesh.
 
+[IMPORTANT]
+====
+Shader Nodes only work if there is no shader declared in the technique. If you want to bypass the Shader Nodes, you can put a VertexShader and a FragmentShader statement in the technique and the shader nodes will be ignored. 
+====
 
 
-[source,java]
 
+[source,java]
 ----
 
 MaterialDef Simple {
@@ -379,7 +376,6 @@ here is the definition content (Common/MatDefs/ShaderNodes/Common/CommonVert.j3s
 
 
 [source,java]
-
 ----
 
 ShaderNodesDefinitions {
@@ -418,11 +414,15 @@ ShaderNodesDefinitions {
 ----
 
 
+[TIP]
+====
+Note that texCoord1/2 and vertColor are declared both as input and output. the generator will use the same variables for them
+====
+
 here is the shader Node code ( Common/MatDefs/ShaderNodes/Common/commonVert.vert)
 
 
 [source,java]
-
 ----
 
 void main(){
@@ -444,6 +444,16 @@ here we have the most basic yet mandatory thing in a vertex shader, computing ve
 *  *modelPosition = Global.position.xyz* : the modelPosition (understand the vertex position in the model coordinate space) is assigned with the Global position variable.
 
 
+[TIP]
+====
+As mentioned before Global position is initialized with the attribute inPosition, so this is equivalent to : modelPosition = Attr.inPosition.xyz
+====
+
+
+[TIP]
+====
+also note the swizzle of the Global.position variable. modelPosition is a vec3 and GlobalPosition is a vec4 so we just take the first 3 components.
+====
 
 +++<u>*CommonVert output mapping*</u>++++
 
@@ -452,6 +462,11 @@ here we have the most basic yet mandatory thing in a vertex shader, computing ve
 *  *Global.position = projPosition* : The result of the multiplication of the worldViewProjectionMatrix  and the modelPosition is assigned to the Globale position
 
 
+[TIP]
+====
+The Global.position variable will be assigned to the gl_Position glsl built in output at the end of the shader.
+====
+
 +++<u>*ColorMult Definition*</u>++++
 
 ColorMult is a very basic Shader Node that takes two colors as input and multiply them.
@@ -459,7 +474,6 @@ here is the definition content (Common/MatDefs/ShaderNodes/Basic/ColorMult.j3sn)
 
 
 [source,java]
-
 ----
 
 ShaderNodeDefinitions{
@@ -488,7 +502,6 @@ here is the shader Node code (Common/MatDefs/ShaderNodes/Basic/colorMult.frag)
 
 
 [source,java]
-
 ----
 
 void main(){
@@ -512,17 +525,31 @@ All inputs are mapped here :
 *  *Global.color = outColor* : the resulting color is assigned to the Global color variable.
 
 
+[TIP]
+====
+Note that the Global.color variable will be assigned to gl_FragColor (glsl &lt; 1.5) or declared as a Global ouput of the shader (glsl &gt;= 1.5).
+====
+
+
+[TIP]
+====
+Also note that in case several Global variables are declared, the generator will assign them gl_FragData[i](glsl &lt; 1.5) i being the order the variable has been found in the material def. For glsl &gt;= 1.5 the veriable will just all be declared as shader output in the order they've been found in the declaration
+====
 
 
 
 +++<u>*Generated shader code*</u>++++
 
 
+[IMPORTANT]
+====
+Don't take this code as carved in stone, the generated code can change as optimization of the shader generator goes on
+====
+
 Vertex Shader (glsl 1.0)
 
 
 [source,java]
-
 ----
 
 
@@ -567,7 +594,6 @@ Fragment Shader (glsl 1.0)
 
 
 [source,java]
-
 ----
 
 
@@ -593,6 +619,11 @@ Same as for the Vertex shader. note that the color1 is not declared, because it'
 
 
 
+[IMPORTANT]
+====
+As a rule of thumb you should not assign a value to an input. input are likely to be material paramters or  outputs from other shaders and modifying them may cause unexpected behavior, even failure in your resulting shader.
+====
+
 
 
 For more explanations and design decisions please refer to the +++<abbr title="specification">spec</abbr>+++ here 

src/docs/asciidoc/jme3/advanced/jme3_shaders.adoc

@@ -79,7 +79,6 @@ Vertex Shader : +
 
 
 [source,java]
-
 ----
 
 //the global uniform World view projection matrix
@@ -105,7 +104,6 @@ Fragment Shader : +
 
 
 [source,java]
-
 ----
 
 void main(){
@@ -137,7 +135,6 @@ For example let’s have a look at the SolidColor.j3md file : +
 
 
 [source,java]
-
 ----
 
 MaterialDef Solid Color {
@@ -230,7 +227,6 @@ Any uniform has to be declared in the material definition file (.j3md) in the
 
 
 [source,java]
-
 ----
 
     MaterialParameters {
@@ -247,7 +243,6 @@ You simply add it in the Defines section of your Technique in the definition fil
 
 
 [source,java]
-
 ----
 
     Defines {
@@ -270,7 +265,6 @@ there are setXXXX methods for any type of uniform you want to pass.+
 
 
 [source,java]
-
 ----
 
    material.setColor("Color", new ColorRGBA(1.0f, 0.0f, 0.0f, 1.0f); // red color
@@ -285,7 +279,6 @@ You can make use of the defines here and later in the code:
 
 
 [source,java]
-
 ----
 
    uniform vec4 m_Color;
@@ -319,7 +312,6 @@ We need to pass 2 new parameters to the Lighting.j3md definition, MaterialParame
 
 
 [source,java]
-
 ----
 
 // Keying Map
@@ -334,7 +326,6 @@ Below, add a new Define in the main Technique section:
 
 
 [source,java]
-
 ----
 
 KEYMAP : KeyMap
@@ -345,7 +336,6 @@ In the Lighting.frag file, define the new uniforms:
 
 
 [source,java]
-
 ----
 
 #ifdef KEYMAP
@@ -360,7 +350,6 @@ if we need to blend it:
 
 
 [source,java]
-
 ----
 
     #ifdef KEYMAP
@@ -389,7 +378,6 @@ A result preview can be seen here: link:http://wstaw.org/m/2011/10/24/plasma-des
 *  That’s it!!
 
 [source,java]
-
 ----
 
     // A cube

src/docs/asciidoc/jme3/advanced/jme3_srgbpipeline.adoc

@@ -67,6 +67,11 @@ image:http://i.imgur.com/uNL7vw8.png[uNL7vw8.png,with="",height=""]
 
 Gamma Correction in jME 3.0 is based on those three statements.
 
+[IMPORTANT]
+====
+Note that Gamma Correction is only available on desktop with LWJGL or JOGL renderer. They are not yet supported on Android or iOS renderers
+====
+
 
 
 
@@ -77,7 +82,6 @@ use this in the main() method of your application :
 
 
 [source,java]
-
 ----
 
 AppSettings settings = new AppSettings(true);
@@ -91,7 +95,12 @@ This setting is also exposed in the Settings dialog displayed when you launch a
 image:http://i.imgur.com/Lya1ldH.png[Lya1ldH.png,with="400",height=""]
 
 
-* But both can be enabled separately*
+
+[IMPORTANT]
+====
+This is a short hand to enable both linearization of input textures and Gamma correction of the rendered output on screen.* But both can be enabled separately*.
+
+====
 
 
 
@@ -102,7 +111,6 @@ You can enable or disable the Gamma correction of the rendered output by using
 
 
 [source,java]
-
 ----
 renderer.setMainFrameBufferSrgb(boolean srgb)
 ----
@@ -125,13 +133,17 @@ You can enable or disable texture linearization by using
 
 
 [source,java]
-
 ----
 renderer.setLinearizeSrgbImages(boolean linearize)
 ----
 
 This will be ignored if the hardware doesn't have the GL_ARB_framebuffer_sRGB or the GL_EXT_texture_sRGB.
 
+[IMPORTANT]
+====
+Toggling this setting at runtime will produce unexpected behavior for now. A change in this setting would need a proper reload of the context to work.
+====
+
 
 
 All images marked as in sRGB color space will be uploaded to the GPU using a sRGB image format.
@@ -156,13 +168,23 @@ Here is an exhaustive list of the supported format and there equivalent :
 *  DXT5 : GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5  
 
 
+[IMPORTANT]
+====
+Conventionally only the rgb channels are gamma corrected, as the alpha channel does not a represent a color value
+====
+
 
 
 
 ==== Excluding images from the sRGB pipeline
 
-+
 
+[IMPORTANT]
+====
+Only loaded images will be marked as in sRGB color space, when using assetManager.loadTexture or loadAsset.+
+
+The color space of an image created by code will have to be specified in the constructor or will be assumed as Linear if not specified. 
+====
 
 
 
@@ -180,7 +202,6 @@ For example here is how the NormalMap parameter is declared in the lighting mate
 
 
 [source]
-
 ----
 
  // Normal map
@@ -198,7 +219,12 @@ This can sound complicated, but you just have to answer this question :  Does my
 
 ==== ColorRGBA as sRGB
 
-*ALWAYS*
+
+[IMPORTANT]
+====
+The r, g, b attributes of a ColorRGBA object are *ALWAYS* assumed in Linear color space.
+
+====
 
 
 

src/docs/asciidoc/jme3/advanced/level_of_detail.adoc

@@ -91,6 +91,11 @@ The LODs are saved in the .j3o model file.
 
 
 
+[TIP]
+====
+Choose Window>Properties if the Properties window is not open. Choose the generated LODs from the dropdown in the Properties window, and verify their quality in the SceneComposer.
+====
+
 
 
 
@@ -105,7 +110,6 @@ The `jme3tools.optimize.LodGenerator` utility class helps you generate LODs for
 
 
 [source,java]
-
 ----
 LodGenerator lod = new LodGenerator(geometry);
 lod.bakeLods(reductionMethod,reductionValue);
@@ -118,7 +122,6 @@ The LODs are stored inside the Geometry object.
 
 
 [source,java]
-
 ----
 LodGenerator lod = new LodGenerator(myPrettyGeo);
 lod.bakeLods(LodGenerator.TriangleReductionMethod.PROPORTIONAL,0.5f);
@@ -131,7 +134,6 @@ After generating the LODs for the geometry, you create and add a `com.jme3.scene
 
 
 [source,java]
-
 ----
 LodControl lc = new LodControl();
 myPrettyGeo.addControl(lc);

src/docs/asciidoc/jme3/advanced/light_and_shadow.adoc

@@ -17,6 +17,11 @@ Light and Shadow are two separate things in 3D engines, although we percieve the
 *  Lighting does not mean that objects cast a shadow on the floor or other objects: Activating shadow processing is an additional step described here. Since casting shadows has an impact on performance, drop shadows and ambient occlusion shading are not activated by default.
 
 
+[IMPORTANT]
+====
+A light source with a direction or location is required for all Geometries with Lighting.j3md-based Materials. An ambient light is not sufficient. In a scene with no appropriate light sources, Geometries with Lighting.j3md-based Materials do not render. Only Geometries with Unshaded.j3md-based Materials are visible independent of any light sources.
+====
+
 
 
 
@@ -62,7 +67,6 @@ A PointLight has a location and shines from there in all directions as far as it
 
 
 [source,java]
-
 ----
 PointLight lamp_light = new PointLight();
 lamp_light.setColor(ColorRGBA.Yellow);
@@ -86,7 +90,6 @@ A DirectionalLight has no position, only a direction. It sends out parallel beam
 
 
 [source,java]
-
 ----
 DirectionalLight sun = new DirectionalLight();
 sun.setColor(ColorRGBA.White);
@@ -109,7 +112,6 @@ A SpotLight sends out a distinct beam or cone of light. A SpotLight has a direct
 
 
 [source,java]
-
 ----
 SpotLight spot = new SpotLight();
 spot.setSpotRange(100f);                           // distance
@@ -134,15 +136,19 @@ An AmbientLight simply influences the brightness and color of the scene globally
 
 
 [source,java]
-
 ----
 AmbientLight al = new AmbientLight();
 al.setColor(ColorRGBA.White.mult(1.3f));
 rootNode.addLight(al);
 ----
 
-+
-`mylight.setColor(ColorRGBA.White.mult(1.3f));`
+
+[TIP]
+====
+You can increase the brightness of a light source gradually by multiplying the light color to values greater than 1.0f. +
+Example: `mylight.setColor(ColorRGBA.White.mult(1.3f));`
+====
+
 
 
 
@@ -152,7 +158,6 @@ You can use a `com.jme3.scene.control.LightControl` to make a SpotLight or Point
 
 
 [source,java]
-
 ----
 
 PointLight myLight = new PointLight();
@@ -213,7 +218,6 @@ Shadow calculations (cast and receive) have a performance impact, so use them sp
 
 
 [source,java]
-
 ----
 
 spatial.setShadowMode(ShadowMode.Inherit);     // This is the default setting for new spatials.
@@ -237,7 +241,6 @@ Here is the key code fragment:
 
 
 [source,java]
-
 ----
 
         DirectionalLight sun = new DirectionalLight();
@@ -287,7 +290,6 @@ image::jme3/advanced/shadow.png[A lit scene with PSSM drop shadows,with="300",he
 
 
 [source,java]
-
 ----
 private PssmShadowRenderer pssmRenderer;
 ...
@@ -316,7 +318,6 @@ In JME3, SSAO is implemented by adding an instance of `com.jme3.post.SSAOFilter`
 
 
 [source,java]
-
 ----
 
 FilterPostProcessor fpp = new FilterPostProcessor(assetManager);

src/docs/asciidoc/jme3/advanced/loading_screen.adoc

@@ -32,7 +32,6 @@ nifty_loading.xml
 
 
 [source,xml]
-
 ----
 
 <?xml version="1.0" encoding="UTF-8"?>
@@ -84,7 +83,6 @@ A custom control is created, which represents the progress bar.
 
 
 [source,xml]
-
 ----
 
     <controlDefinition name = "loadingbar" controller = "jme3test.TestLoadingScreen">
@@ -101,7 +99,6 @@ This screen simply displays a button in the middle of the screen, which could be
 
 
 [source,xml]
-
 ----
 
     <screen id="start" controller = "jme3test.TestLoadingScreen">
@@ -121,7 +118,6 @@ This screen displays our custom progress bar control with a text control
 
 
 [source,xml]
-
 ----
 
     <screen id="loadlevel" controller = "jme3test.TestLoadingScreen">
@@ -146,7 +142,6 @@ Something like this in a single thread will not work:
 
 
 [source,java]
-
 ----
 
 load_scene();
@@ -174,7 +169,6 @@ The idea is to break down the loading of the game into discrete parts
 
 
 [source,java]
-
 ----
 
 package jme3test;
@@ -368,7 +362,6 @@ Make sure to change the XML file to point the controller to TestLoadingScreen*1*
 
 
 [source,java]
-
 ----
 
 package jme3test;

src/docs/asciidoc/jme3/advanced/localization.adoc

@@ -34,7 +34,6 @@ To prepare the application for localization, you have to first identify all hard
 .  Find every line in your jME3 game where you hard-coded message strings, e.g. +
 
 [source,java]
-
 ----
 System.out.print("Hello World!");
 UiText.setText("Score: "+score);
@@ -44,7 +43,6 @@ UiText.setText("Score: "+score);
 .  For every hard-coded message, you add one line to the `Bundle.properties` file: First specify a unique key that identifies this string; then an equal sign; and the literal string itself. +
 
 [source]
-
 ----
 greeting=Hello World!
 score.display=Score: 
@@ -52,7 +50,6 @@ score.display=Score:
 
 .  In the source code, replace every occurence of a hard-coded message with the appropriate Resource Bundle call to its unique key: 
 [source,java]
-
 ----
 System.out.print(ResourceBundle.getBundle("Bundle").getString("greeting"));
 UiText.setText(ResourceBundle.getBundle("Bundle").getString("score.display")+score);
@@ -75,7 +72,6 @@ To translate the messages to another language, for example, German:
 .  Name the copy `Bundle_de.properties` for German. Note the added suffix _de.
 .  Translate all strings (text on the right side of the equal sign) in the `Bundle_de.properties` to German. 
 [source]
-
 ----
 greeting=Hallo Welt!
 score.display=Spielstand: 
@@ -93,7 +89,6 @@ To get the full list of language suffixes use
 
 
 [source,java]
-
 ----
 System.out.println(Arrays.toString(Locale.getISOLanguages()));
 ----
@@ -106,21 +101,18 @@ System.out.println(Arrays.toString(Locale.getISOLanguages()));
 
 *  Keep material layers: 
 [source,java]
-
 ----
 mat.setTexture("ColorMap", tex);
 ----
 
 *  Keep paths: 
 [source,java]
-
 ----
 teapot = assetManager.loadModel("Models/Teapot/Teapot.obj");
 ----
 
 *  Keep geometry and node names: 
 [source,java]
-
 ----
 Geometry thing=new Geometry("A thing", mesh);
 Node vehicle = new Node("Vehicle");
@@ -128,7 +120,6 @@ Node vehicle = new Node("Vehicle");
 
 *  Keep mappings: 
 [source,java]
-
 ----
 inputManager.addMapping("Shoot", trigger);
 inputManager.addListener(actionListener, "Shoot");

src/docs/asciidoc/jme3/advanced/logging.adoc

@@ -31,7 +31,6 @@ To print comments like a pro, you use the following logger syntax.
 
 .  Declare the logger object once per file. In the following code, replace `HelloWorld` by the name of the class where you are using this line.
 [source,java]
-
 ----
 private static final Logger logger = Logger.getLogger(HelloWorld.class.getName());
 ----
@@ -42,7 +41,6 @@ Example: `Vector3f a = cam.getLocation();`
 .  Add the logger line and specify the log level:
 **  Usecase 1: During debugging, a developer uses a warning to remind himself of a bug:
 [source,java]
-
 ----
 logger.log(Level.WARNING, "why is {0} set to {1} again?!", 
                       new Object[]{a , b});
@@ -50,7 +48,6 @@ logger.log(Level.WARNING, "why is {0} set to {1} again?!",
 
 **  Usecase 2: For the release, you inform the customer of a problem and how to solve it. 
 [source,java]
-
 ----
 logger.log(Level.SEVERE, "MyGame error: {0} must not be {1} after {2}! Adjust flux generator settings.", 
                       new Object[]{a , b , c});
@@ -58,7 +55,12 @@ logger.log(Level.SEVERE, "MyGame error: {0} must not be {1} after {2}! Adjust fl
 
 
 
-“_a reason and a solution_
+
+[IMPORTANT]
+====
+As you see in the examples, you should phrase potentially “customer facing errors in a neutral way and offer _a reason and a solution_ for the error (if you don't, it has no value to your customer). If your deveopment team uses WARNINGs as replacement for casual printlns, make sure you deactivate them for the release.
+====
+
 
 
 More details about link:http://download.oracle.com/javase/6/docs/api/java/util/logging/Level.html[Java log levels] here.
@@ -74,7 +76,6 @@ To deactivate the default logger for a release, you set the log level to only re
 
 
 [source,java]
-
 ----
 Logger.getLogger(””).setLevel(Level.SEVERE);
 ----
@@ -83,7 +84,6 @@ During development or a beta test, you can tune down the default logger, and set
 
 
 [source,java]
-
 ----
 Logger.getLogger(””).setLevel(Level.WARNING);
 ----
@@ -92,7 +92,6 @@ To activate full logging, e.g. for debugging and testing, use the `fine` level:
 
 
 [source,java]
-
 ----
 Logger.getLogger(””).setLevel(Level.FINE);
 ----

src/docs/asciidoc/jme3/advanced/making_the_camera_follow_a_character.adoc

@@ -35,7 +35,6 @@ To make the camera follow a target node, add this camera node code to your init
 
 
 [source,java]
-
 ----
 
 // Disable the default flyby cam
@@ -84,7 +83,6 @@ To activate the chase camera, add the following code to your init method (e.g. `
 
 
 [source,java]
-
 ----
 
 // Disable the default flyby cam

src/docs/asciidoc/jme3/advanced/material_definitions.adoc

@@ -18,7 +18,6 @@ The most common Material Definitions are included in the engine, advanced users
 
 
 [source,java]
-
 ----
 Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
 Material mat = new Material(assetManager,  // Create new material and...
@@ -28,7 +27,12 @@ myGeometry.setMaterial(mat);               // Use material on this Geometry.
 
 ----
 
-<<jme3/advanced/j3m_material_files#,j3m Material Files>><<sdk/material_editing#,use the jMonkeyEngine SDK to create .j3m files>><<jme3/advanced/j3m_material_files#,write .j3m files in a text editor>>
+
+[TIP]
+====
+If you use one custom material with certain settings very often, learn about storing material settings in <<jme3/advanced/j3m_material_files#,j3m Material Files>>. You either <<sdk/material_editing#,use the jMonkeyEngine SDK to create .j3m files>> (user-friendly), or you <<jme3/advanced/j3m_material_files#,write .j3m files in a text editor>> (IDE-independent).
+====
+
 
 
 
@@ -56,28 +60,24 @@ In your Java code,
 
 .  Create a Material object based on the chosen Material Definition (.j3md file): 
 [source,java]
-
 ----
 Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
 ----
 
 .  Configure your Material by setting the appropriate values listed in the <<jme3/advanced/materials_overview#,Materials Overview>> table. 
 [source,java]
-
 ----
 mat.setColor("Color", ColorRGBA.Yellow ); // and more
 ----
 
 .  Apply your prepared Material to a Geometry: 
 [source,java]
-
 ----
 myGeometry.setMaterial(mat);
 ----
 
 .  (Optional) Adjust the texture scale of the mesh: 
 [source,java]
-
 ----
 myGeometryMesh.scaleTextureCoordinates(new Vector2f(2f, 2f));
 ----
@@ -102,7 +102,6 @@ A simpled textured material.
 
 
 [source,java]
-
 ----
 
 Material mat = new Material(assetManager, 
@@ -116,7 +115,6 @@ A textured material with a color bleeding through transparent areas.
 
 
 [source,java]
-
 ----
 
 Material mat = new Material(assetManager, 
@@ -131,7 +129,6 @@ You can test these examples within the following code snippet. It creates a box
 
 
 [source,java]
-
 ----
  Box b = new Box(Vector3f.ZERO, 1, 1, 1);
 Geometry geom = new Geometry("Box", b);
@@ -142,6 +139,11 @@ rootNode.attachChild(geom);
 ----
 
 
+[TIP]
+====
+You can find these and other common code snippets in the jMonkeyEngine SDK Code Palette. Drag and drop them into your source code.
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/material_specification.adoc

@@ -17,7 +17,6 @@ Material definitions and material instance files are formatted similarly to curl
 
 
 [source]
-
 ----
 RootBlock {
   // Comment
@@ -73,7 +72,6 @@ All J3MD files begin with `MaterialDef` as the root block, following that, is th
 
 
 [source]
-
 ----
 MaterialDef Test Material 123 {
 ----
@@ -88,7 +86,6 @@ Techniques may have an optional name, which specifies the name of the technique.
 
 
 [source]
-
 ----
 MaterialDef Test Material 123 { 
   MaterialParameters { }
@@ -104,7 +101,6 @@ Inside the MaterialParameters block, the parameters are specified. Every paramet
 
 
 [source]
-
 ----
 MaterialParameters {
     Texture2D TexParam
@@ -125,7 +121,6 @@ You can specify a default value for material parameters, inside material definit
 
 
 [source]
-
 ----
 MaterialParameters {
      Float MyParam : 1
@@ -155,7 +150,6 @@ For example, assuming the parameter `Shininess` is defined in the MaterialParame
 
 
 [source]
-
 ----
 MaterialParameters {
   Float Shininess
@@ -166,7 +160,6 @@ The value of that parameter will map into an uniform with same name with the “
 
 
 [source]
-
 ----
 uniform float m_Shininess;
 ----
@@ -181,7 +174,6 @@ An important structure, that also relates to shaders, is the WorldParameters str
 
 
 [source]
-
 ----
 WorldParameters {
   Time
@@ -193,7 +185,6 @@ The shader will be able to access this parameter through a uniform, also named `
 
 
 [source]
-
 ----
 uniform float g_Time;
 ----
@@ -217,7 +208,6 @@ The most commonly used render state is alpha blending, to specify it for a parti
 
 
 [source]
-
 ----
 RenderState {
  Blend Alpha
@@ -231,7 +221,6 @@ Included is a full example of a J3MD file using all the features learned:
 
 
 [source]
-
 ----
 MaterialDef Test Material 123 { 
   MaterialParameters {
@@ -264,7 +253,6 @@ All J3M files begin with the word `Material` followed by the name of the materia
 
 
 [source]
-
 ----
 Material MyGrass : Common/MatDefs/Misc/TestMaterial.j3md {
 ----
@@ -282,7 +270,6 @@ To specify a value for a parameter, one must specify first the parameter name, f
 
 
 [source]
-
 ----
 MaterialParameters {
   m_Shininess : 20.0 
@@ -327,7 +314,6 @@ The formatting of the value, depends on the type of the value that was specified
 
 
 [source]
-
 ----
 Material MyGrass : Common/MatDefs/Misc/TestMaterial.j3md { 
   MaterialParameters {
@@ -344,7 +330,6 @@ It is possible to generate an identical J3M file using Java code, by using the c
 
 
 [source,java]
-
 ----
 
 // Create a material instance

src/docs/asciidoc/jme3/advanced/materials_overview.adoc

@@ -14,8 +14,13 @@ In jMonkeyEngine 3, colors and textures are represented as Material objects.
 *  All Geometries must have Materials. To improve performance, reuse Materials for similar models, don't create a new Material object for every Geometry. (E.g. use one bark Material for several tree models.) 
 *  Each Material is based on one of jme3's default Material Definitions (.j3md files) that are included in the engine. Advanced users can create additional custom Material Definitions (see how it's done in the <<jme3/build_from_sources#,jme3 sources>>).
 
-<<jme3/intermediate/how_to_use_materials#,How to Use Materials>>+
-<<jme3/advanced/material_definitions#,How to use Material Definitions>>
+
+[TIP]
+====
+Find out quickly <<jme3/intermediate/how_to_use_materials#,How to Use Materials>>, including the most commonly used code samples and RenderStates. +
+Or find more background info on <<jme3/advanced/material_definitions#,How to use Material Definitions>>.
+====
+
 
 
 
@@ -24,10 +29,15 @@ In jMonkeyEngine 3, colors and textures are represented as Material objects.
 The following Materials table shows you the Material Definitions that jMonkeyEngine 3 supports. 
 
 
-+
-`Unshaded.j3md``Lighting.j3md`+
-<<sdk/material_editing#,the SDK's visual material editor>>+
-<<sdk/code_editor#,SDK's Palette>>
+
+[TIP]
+====
+Looks confusing? +
+1) Start learning about `Unshaded.j3md` and `Lighting.j3md`, they cover 90% of the cases. +
+2) Use <<sdk/material_editing#,the SDK's visual material editor>> to try out and save material settings easily. +
+3) The <<sdk/code_editor#,SDK's Palette>> contains drag&amp;drop code snippets for loading materials. 
+====
+
 
 
 Most Material parameters are optional. For example, it is okay to specify solely the `DiffuseMap` and `NormalMap` when using `Lighting.j3md`, and leave the other texture maps empty. In this case, you are only using a subset of the possible features, but that's fine if it already makes in the material look the way that you want. You can always add more texture maps later.
@@ -312,7 +322,6 @@ If the DiffuseMap has an alpha channel, use:
 
 
 [source,java]
-
 ----
 mat.setBoolean("UseAlpha",true);
 ----
@@ -322,14 +331,12 @@ Later, put the Geometry (not the Material!) in the appropriate render queue
 
 *  
 [source,java]
-
 ----
 geo.setQueueBucket(Bucket.Translucent);
 ----
 
 *  
 [source,java]
-
 ----
 geo.setQueueBucket(Bucket.Transparent);
 ----

src/docs/asciidoc/jme3/advanced/motionpath.adoc

@@ -41,7 +41,6 @@ Create a Motionpath object and add way points to it.
 
 
 [source,java]
-
 ----
 MotionPath path = new MotionPath();
 path.addWayPoint(new Vector3f(10, 3, 0));
@@ -92,7 +91,6 @@ In this example, you just print the status at every way point. In a game you cou
 
 
 [source,java]
-
 ----
 path.addListener( new MotionPathListener() {
   public void onWayPointReach(MotionTrack control, int wayPointIndex) {

src/docs/asciidoc/jme3/advanced/mouse_picking.adoc

@@ -32,7 +32,6 @@ The following example rotates Spatials named “Red Box or “Blue Box when they
 
 
 [source,java]
-
 ----
 
   private AnalogListener analogListener = new AnalogListener() {
@@ -87,7 +86,6 @@ The following example rotates Spatials named “Red Box or “Blue Box when they
 
 
 [source,java]
-
 ----
 
 private AnalogListener analogListener = new AnalogListener() {

src/docs/asciidoc/jme3/advanced/multiple_camera_views.adoc

@@ -24,7 +24,6 @@ Imagine the window as a 1.0f x 1.0f rectangle. The default cam's viewPort is set
 
 
 [source,java]
-
 ----
 cam.setViewPort(0f, 1f, 0f, 1f);
 ----
@@ -36,7 +35,6 @@ The four values are read in the following order:
 
 
 [source,java]
-
 ----
 cam.setViewPort(x1,x2 , y1,y2);
 ----
@@ -48,7 +46,6 @@ Here are a few examples:
 
 
 [source,java]
-
 ----
 
 cam1.setViewPort( 0.0f , 1.0f   ,   0.0f , 1.0f );
@@ -60,7 +57,6 @@ These viewport parameters are, (in this order) the left-right extend, and the bo
 
 
 [source]
-
 ----
 
 0.0 , 1.0       1.0 , 1.0
@@ -77,7 +73,12 @@ These viewport parameters are, (in this order) the left-right extend, and the bo
 Example: Cam2's rectangle is in the bottom right: It extends from mid (x1=0.5f) bottom (y1=0.0f), to right (x2=1.0f) mid (y2=0.5f)
 
 
-`Camera cam5 = new Camera(100,100);`
+
+[IMPORTANT]
+====
+If you scale the views in a way so that the aspect ratio of a ViewPort is different than the window's aspect ratio, then the ViewPort appears distorted. In these cases, you must recreate (not clone) the ViewPort's cam object with the right aspect ratio. For example: `Camera cam5 = new Camera(100,100);` 
+====
+
 
 
 
@@ -93,7 +94,6 @@ You use the preconfigured Camera `cam` and `viewPort` from `SimpleApplication` f
 
 
 [source,java]
-
 ----
 
 cam.setViewPort(.5f, 1f, 0f, 0.5f); // Resize the viewPort to half its size, bottom right.
@@ -104,7 +104,6 @@ Optionally, place the main camera in the scene and rotate it in its start positi
 
 
 [source,java]
-
 ----
 cam.setLocation(new Vector3f(3.32f, 4.48f, 4.28f));
 cam.setRotation(new Quaternion (-0.07f, 0.92f, -0.25f, -0.27f));
@@ -129,7 +128,6 @@ Here is the abstract code sample for camera `n`:
 
 
 [source,java]
-
 ----
 
 Camera cam_n    = cam.clone();
@@ -148,7 +146,6 @@ To visualize what you do, use the following drawing of the viewport positions:
 
 
 [source]
-
 ----
 
 0.0 , 1.0       1.0 , 1.0
@@ -166,7 +163,6 @@ This are the lines of code that set the four cameras to create a four-times spli
 
 
 [source,java]
-
 ----
 
 cam1.setViewPort( 0.5f , 1.0f  ,  0.0f , 0.5f);
@@ -186,7 +182,6 @@ The following code snippet sets up two views, one covers the whole screen, and t
 
 
 [source]
-
 ----
 
        +-----+-----+
@@ -200,7 +195,6 @@ The following code snippet sets up two views, one covers the whole screen, and t
 ----
 
 [source,java]
-
 ----
 
 // Setup first full-window view
@@ -226,7 +220,6 @@ You can customize the camera and the viewPort of each view individually. For exa
 
 
 [source,java]
-
 ----
 viewPort.setBackgroundColor(ColorRGBA.Blue);
 ----
@@ -235,7 +228,6 @@ You have full control to determine which Nodes the camera can see! It can see th
 
 
 [source,java]
-
 ----
 viewPort1.attachScene(rootNode);
 ----
@@ -244,7 +236,6 @@ viewPort1.attachScene(rootNode);
 
 
 [source,java]
-
 ----
 viewPort2.attachScene(spookyGhostDetectorNode);
 ----

src/docs/asciidoc/jme3/advanced/multithreading.adoc

@@ -15,7 +15,6 @@ jME3 is similar to Swing in that, for speed and efficiency, all changes to the s
 
 
 [source,java]
-
 ----
 
 public void rotateGeometry(final Geometry geo, final Quaternion rot) {
@@ -75,7 +74,6 @@ You create the executor object in a global AppState (or the initSimpleApp() meth
 
 
 [source,java]
-
 ----
 
 /* This constructor creates a new executor with a core pool size of 4. */
@@ -91,7 +89,6 @@ In your simple application you can override the destroy method and shutdown the
 
 
 [source,java]
-
 ----
 
     @Override
@@ -109,7 +106,6 @@ In the NPC Control, we create the individual objects that the thread manipulates
 
 
 [source,Java]
-
 ----
 
 //The vector to store the desired location in:
@@ -131,7 +127,6 @@ Next let's look at the update() call of the Control where the time-intensive tas
 
 
 [source,java]
-
 ----
 
 public void update(float tpf) {
@@ -193,7 +188,6 @@ These two ways are thread-safe, they don't mess up the game logic, and keep the
 
 
 [source,java]
-
 ----
 
 // A self-contained time-intensive task:

src/docs/asciidoc/jme3/advanced/networking.adoc

@@ -56,7 +56,6 @@ The game server is a “headless com.jme3.app.SimpleApplication:
 
 
 [source,java]
-
 ----
 
 public class ServerMain extends SimpleApplication {
@@ -68,14 +67,18 @@ public class ServerMain extends SimpleApplication {
 
 ----
 
-`Headless`
+
+[TIP]
+====
+A `Headless` SimpleApplication executes the simpleInitApp() method and runs the update loop normally. But the application does not open a window, and it does not listen to user input. This is the typical behavior for a server application.
+====
+
 
 
 Create a com.jme3.network.Server in the `simpleInitApp()` method and specify a communication port, for example 6143.
 
 
 [source,java]
-
 ----
 
   public void simpleInitApp() {
@@ -97,7 +100,6 @@ A game client is a standard com.jme3.app.SimpleApplication.
 
 
 [source,java]
-
 ----
 
 public class ClientMain extends SimpleApplication {
@@ -109,14 +111,18 @@ public class ClientMain extends SimpleApplication {
 
 ----
 
-`Display`
+
+[TIP]
+====
+A standard SimpleApplication in `Display` mode executes the simpleInitApp() method, runs the update loop, opens a window for the rendered video output, and listens to user input. This is the typical behavior for a client application.
+====
+
 
 
 Create a com.jme3.network.Client in the `simpleInitApp()` method and specify the servers IP address, and the same communication port as for the server, here 6143.
 
 
 [source,java]
-
 ----
 
 public void simpleInitApp() {
@@ -181,7 +187,6 @@ Each message represents data that you want to transmit between client and server
 
 
 [source,java]
-
 ----
 
 @Serializable
@@ -197,7 +202,6 @@ You must register each message type to the com.jme3.network.serializing.Serializ
 
 
 [source,java]
-
 ----
 Serializer.registerClass(HelloMessage.class);
 ----
@@ -215,7 +219,6 @@ Create one ClientListener.java and make it extend `com.jme3.network.MessageListe
 
 
 [source,java]
-
 ----
 public class ClientListener implements MessageListener<Client> {
   public void messageReceived(Client source, Message message) {
@@ -231,7 +234,6 @@ For each message type, register a client listener to the client.
 
 
 [source,java]
-
 ----
 myClient.addMessageListener(new ClientListener(), HelloMessage.class);
 ----
@@ -243,7 +245,6 @@ Create one ServerListener.java and make it extend `com.jme3.network.MessageListe
 
 
 [source,java]
-
 ----
 public class ServerListener implements MessageListener<HostedConnection> {
   public void messageReceived(HostedConnection source, Message message) {
@@ -259,7 +260,6 @@ For each message type, register a server listener to the server:
 
 
 [source,java]
-
 ----
 myServer.addMessageListener(new ServerListener(), HelloMessage.class);
 ----
@@ -271,7 +271,6 @@ Let's create a new message of type HelloMessage:
 
 
 [source,java]
-
 ----
 Message message = new HelloMessage("Hello World!");
 ----
@@ -280,7 +279,6 @@ Now the client can send this message to the server:
 
 
 [source,java]
-
 ----
 myClient.send(message);
 ----
@@ -289,7 +287,6 @@ Or the server can broadcast this message to all HostedConnection (clients):
 
 
 [source,java]
-
 ----
 Message message = new HelloMessage("Welcome!");
 myServer.broadcast(message);
@@ -299,7 +296,6 @@ Or the server can send the message to a specific subset of clients (e.g. to Host
 
 
 [source,java]
-
 ----
 myServer.broadcast( Filters.in( conn1, conn2, conn3 ), message );
 ----
@@ -308,7 +304,6 @@ Or the server can send the message to all but a few selected clients (e.g. to al
 
 
 [source,java]
-
 ----
 myServer.broadcast( Filters.notEqualTo( conn4 ), message );
 ----
@@ -323,7 +318,6 @@ The ID of the Client and HostedConnection are the same at both ends of a connect
 
 
 [source,java]
-
 ----
 ... myClient.getId() ...
 ----
@@ -332,6 +326,11 @@ A server has a game version and game name property. Each client expects to commu
 
 
 
+[TIP]
+====
+Typically, your networked game defines its own attributes (such as player ID) based on whatever criteria you want. If you want to look up player/client-specific information beyond the game version, you can set this information directly on the Client/HostedConnection object (see Getting Info About a Client).
+====
+
 
 
 
@@ -344,7 +343,6 @@ You must override the client's destroy() method to close the connection cleanly
 
 
 [source,java]
-
 ----
 
   @Override
@@ -362,7 +360,6 @@ You must override the server's destroy() method to close the connection when the
 
 
 [source,java]
-
 ----
 
   @Override
@@ -380,7 +377,6 @@ The server can kick a HostedConnection to make it disconnect. You should provide
 
 
 [source,java]
-
 ----
 conn.close("We kick cheaters.");
 ----
@@ -398,6 +394,11 @@ The com.jme3.network.ClientStateListener notifies the Client when the Client has
 
 
 
+[TIP]
+====
+The ClientStateListener when it receives a network exception applies the default close action. This just stops the client and you'll have to build around it so your application knows what to do. If you need more control when a network exception happens and the client closes, you may want to investigate in a ErrorListener.
+====
+
 
 [cols="2", options="header"]
 |===
@@ -417,7 +418,6 @@ First implement the ClientStateListener interface in the Client class. Then regi
 
 
 [source,java]
-
 ----
 myClient.addClientStateListener(this);
 ----
@@ -445,7 +445,6 @@ First implement the ConnectionListener interface in the Server class. Then regis
 
 
 [source,java]
-
 ----
 myServer.addConnectionListener(this);
 ----
@@ -456,7 +455,12 @@ myServer.addConnectionListener(this);
 The com.jme3.network.ErrorListener is a listener for when network exception happens. This listener is built so that you can override the default actions when a network exception happens.
 
 
-*don't*
+
+[IMPORTANT]
+====
+If you intend on using the default network mechanics, *don't* use this!
+If you do override this, make sure you add a mechanic that can close the client otherwise your client will get stuck open and cause errors.
+====
 
 
 [cols="2", options="header"]
@@ -471,13 +475,17 @@ a| Implemenent here what happens after a exception affects the network .
 |===
 
 
+[TIP]
+====
+This interface was built for the client and server, but the code has never been put on the server to handle this listener.
+====
+
 
 
 First implement the ErrorListener interface in the client class. Then you need to register it to myClient in MyGameClients's simpleInitApp() method.
 
 
 [source,java]
-
 ----
 myClient.addErrorListener(this);
 ----
@@ -486,7 +494,6 @@ In the class that implements the ErrorListener, a method would of been added cal
 
 
 [source,java]
-
 ----
 if(t instanceof exception) {
      //Add your own code here
@@ -503,7 +510,6 @@ SpiderMonkey supports both UDP (unreliable, fast) and TCP (reliable, slow) trans
 
 
 [source,java]
-
 ----
 message1.setReliable(true); // TCP
 message2.setReliable(false); // UDP
@@ -515,14 +521,18 @@ message2.setReliable(false); // UDP
 
 == Important: Use Multi-Threading
 
-*You cannot modify the scenegraph directly from the network thread.*
+
+[IMPORTANT]
+====
+*You cannot modify the scenegraph directly from the network thread.* A common example for such a modification is when you synchronize the player's position in the scene. You have to use Java Multithreading.
+====
+
 
 
 Multithreading means that you create a Callable. A Callable is a Java class representing any (possibly time-intensive) self-contained task that has an impact on the scene graph (such as positioning the player). You enqueue the Callable in the Executor of the client's OpenGL thread. The Callable ensures to executes the modification in sync with the update loop.
 
 
 [source,java]
-
 ----
 app.enqueue(callable);
 ----

src/docs/asciidoc/jme3/advanced/nifty_gui.adoc

@@ -114,7 +114,6 @@ If you want to disable the nifty log lines, add this code after you created nift
 
 
 [source]
-
 ----
 
 Logger.getLogger("de.lessvoid.nifty").setLevel(Level.SEVERE); 

src/docs/asciidoc/jme3/advanced/nifty_gui_best_practices.adoc

@@ -47,7 +47,6 @@ The link:http://nifty-gui.sourceforge.net/projects/nifty/apidocs/de/lessvoid/nif
 
 *  Include the following XML schema in the first line of your NiftyGUI XML files
 [source,xml]
-
 ----
 
 <?xml version="1.0" encoding="UTF-8"?>
@@ -85,13 +84,17 @@ You can use temporary colors during the design phase to highlight which containe
 In the finished +++<abbr title="Graphical User Interface">GUI</abbr>+++, screens, layers, and panels are typically transparent; the visible elements are the images, text fields, and controls, inside the panels.
 
 
+[TIP]
+====
+During development (and during a tutorial), the following debug code makes all panels visible. This helps you arrange them and find errors. 
 
 
 [source,java]
-
 ----
 nifty.setDebugOptionPanelColors(true);
 ----
 
+Before the release, and during testing, set the debug view to false again.
+====
 
 

src/docs/asciidoc/jme3/advanced/nifty_gui_editor.adoc

@@ -42,6 +42,11 @@ Base on reclucri's Editor, ported to Netbean plugin, with more features included
 ....
 
 
+[IMPORTANT]
+====
+Notice that even it from the same author of Atom framework but it can work separately and not depend on Atom framework. The Extended version of this Nifty Editor, which depend on Atom's component is called TeeHeeGUI!
+====
+
 
 
 Forum:
@@ -54,6 +59,11 @@ Download:
 
 
 
+[IMPORTANT]
+====
+The below Manual belong to Atomix's Nifty Editor!!! You should find the Manual for the orginal Relucri's Nifty Editor above
+====
+
 
 
 

src/docs/asciidoc/jme3/advanced/nifty_gui_java_interaction.adoc

@@ -36,7 +36,6 @@ Continue with adding:
 
 
 [source,java]
-
 ----
 
 import de.lessvoid.nifty.screen.Screen;
@@ -58,7 +57,6 @@ public void onEndScreen() {
 ----
 
 [source,java]
-
 ----
 /*
  * To change this template, choose Tools | Templates
@@ -114,7 +112,6 @@ The name and package of your custom ScreenController class (here `mygame.MyStart
 
 
 [source,xml]
-
 ----
 
 <nifty>
@@ -129,7 +126,6 @@ Or the same in a Java syntax, respectively:
 
 
 [source,java]
-
 ----
 
   nifty.addScreen("start", new ScreenBuilder("start") {{
@@ -172,7 +168,6 @@ In the following example, we call the `startGame()` method when the player click
 
 
 [source,xml]
-
 ----
 
         <panel id="panel_bottom_left" height="50%" width="50%" valign="center" childLayout="center">  
@@ -195,7 +190,6 @@ Or the same in a Java syntax, respectively:
 
 
 [source,java]
-
 ----
 
 control(new ButtonBuilder("StartButton", "Start") {{
@@ -223,7 +217,6 @@ Back in the MyStartScreen class, you specify what the `startGame()` and `quitGam
 
 
 [source,java]
-
 ----
 
 public class MyStartScreen implements ScreenController {
@@ -260,7 +253,6 @@ First define a Java method in the screen controller, in this example, `getPlayer
 
 
 [source,java]
-
 ----
 
 public class MySettingsScreen implements ScreenController {
@@ -276,7 +268,6 @@ Nifty uses `${CALL.getPlayerName()}` to get the return value of the getPlayerNam
 
 
 [source,xml]
-
 ----
 
 <text text="${CALL.getPlayerName()}'s Cool Game" font="Interface/Fonts/Default.fnt" width="100%" height="100%" />
@@ -287,7 +278,6 @@ Or the same in a Java syntax, respectively:
 
 
 [source,java]
-
 ----
 text(new TextBuilder() {{
   text("${CALL.getPlayerName()}'s Cool Game");
@@ -311,7 +301,6 @@ Here's an example of how to change an image called `playerhealth`:
 
 
 [source,java]
-
 ----
 
 // load or create new image
@@ -327,7 +316,6 @@ The same is valid for other elements, for example a text label “score:
 
 
 [source,java]
-
 ----
 
 // find old text
@@ -341,7 +329,6 @@ Similarly, to change the onClick() event of an element, create an `ElementIntera
 
 
 [source,java]
-
 ----
 
 Element niftyElement = nifty.getCurrentScreen().findElementByName("myElement");
@@ -353,7 +340,6 @@ For this to work, there already needs to be a (possibly inactive) `&lt;interact
 
 
 [source,xml]
-
 ----
 <interact onClick="doNothing()"/>
 ----

src/docs/asciidoc/jme3/advanced/nifty_gui_java_layout.adoc

@@ -39,7 +39,6 @@ Just so you get a quick picture what Nifty +++<abbr title="Graphical User Interf
 
 
 [source,java]
-
 ----
 package mygame;
  
@@ -128,7 +127,6 @@ The following minimal Java file contains a start screen and a HUD screen. (Neith
 
 
 [source,java]
-
 ----
 
 nifty.addScreen("start", new ScreenBuilder("start"){{
@@ -153,7 +151,6 @@ The following Java code shows how we add layers to the start screen and HUD scre
 
 
 [source,java]
-
 ----
 
 nifty.addScreen("start", new ScreenBuilder("start"){{
@@ -182,7 +179,6 @@ Repeat the same, but use
 
 
 [source]
-
 ----
 nifty.addScreen("hud", new ScreenBuilder("hud"){{
 ----
@@ -200,7 +196,6 @@ A panel is the inner-most container (that will contain the actual content: text,
 
 
 [source,java]
-
 ----
 
     nifty.addScreen("start", new ScreenBuilder("start") {{
@@ -265,7 +260,6 @@ The following panels go into in the `hud` screen:
 
 
 [source,Java]
-
 ----
 
     nifty.addScreen("hud", new ScreenBuilder("hud") {{
@@ -344,7 +338,6 @@ The start-background.png image is a fullscreen background picture. In the `start
 
 
 [source,java]
-
 ----
 
     nifty.addScreen("start", new ScreenBuilder("start") {{
@@ -366,7 +359,6 @@ The hud-frame.png image is a transparent frame that we use as HUD decoration. In
 
 
 [source,java]
-
 ----
     nifty.addScreen("hud", new ScreenBuilder("hud") {{
         controller(new DefaultScreenController());
@@ -388,7 +380,6 @@ In the `hud` screen's `foreground` layer, add the following image element:
 
 
 [source,java]
-
 ----
                 panel(new PanelBuilder("panel_top_right2") {{
                     childLayoutCenter();
@@ -418,7 +409,6 @@ The game title is a typical example of static text. In the `start` screen, add t
 
 
 [source,java]
-
 ----
 
            // panel added
@@ -444,7 +434,6 @@ For longer pieces of static text, such as an introduction, you can use wrap=“t
 
 
 [source,java]
-
 ----
 
             panel(new PanelBuilder("panel_mid") {{
@@ -476,7 +465,6 @@ Before you can use any control, you must load a Control Definition first. Add th
 
 
 [source,java]
-
 ----
 
     nifty.loadStyleFile("nifty-default-styles.xml");
@@ -491,7 +479,6 @@ In the `hud` screen's `foreground` layer, add the following text element:
 
 
 [source,java]
-
 ----
                 panel(new PanelBuilder("panel_top_right1") {{
                     childLayoutCenter();
@@ -517,7 +504,6 @@ Our +++<abbr title="Graphical User Interface">GUI</abbr>+++ plan asks for two bu
 
 
 [source,java]
-
 ----
 
                 panel(new PanelBuilder("panel_bottom_left") {{
@@ -610,7 +596,6 @@ Example:
 
 
 [source,java]
-
 ----
 nifty.registerMouseCursor("hand", "Interface/mouse-cursor-hand.png", 5, 4);
 ----

src/docs/asciidoc/jme3/advanced/nifty_gui_overlay.adoc

@@ -38,7 +38,6 @@ This code shows you how to overlay anything on the screen with the +++<abbr titl
 
 
 [source,java]
-
 ----
 
 NiftyJmeDisplay niftyDisplay = NiftyJmeDisplay.newNiftyJmeDisplay(
@@ -59,7 +58,6 @@ Currently you do not have a ScreenController – we will create one in the next
 
 
 [source,java]
-
 ----
 nifty.fromXml("Interface/helloworld.xml", "start", new MySettingsScreen());
 ----
@@ -72,7 +70,6 @@ simply added to whatever XML data has been loaded before.
 
 
 [source,java]
-
 ----
 nifty.addXml("Interface/mysecondscreen.xml");
 ----

src/docs/asciidoc/jme3/advanced/nifty_gui_popup_menu.adoc

@@ -12,7 +12,6 @@ The popup element needs to be placed _outside_ of any screen!
 
 
 [source,xml]
-
 ----
 
 <useControls filename="nifty-default-controls.xml"/>
@@ -37,7 +36,6 @@ The Java code within your defined ScreenController implementation:
 
 
 [source,java]
-
 ----
 
 private Element popup;
@@ -82,7 +80,6 @@ To handle menu item events (i.e. calling a method when you click on a menu item)
 
 
 [source,java]
-
 ----
 
   private class MenuItemActivatedEventSubscriber 

src/docs/asciidoc/jme3/advanced/nifty_gui_projection.adoc

@@ -40,7 +40,6 @@ You can project the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>++
 
 
 [source,java]
-
 ----
 
 /** Create a special viewport for the Nifty GUI */

src/docs/asciidoc/jme3/advanced/nifty_gui_scenarios.adoc

@@ -45,7 +45,6 @@ This gives the ScreenController access to the application object and to the upda
 
 
 [source,java]
-
 ----
 
 public class StartScreenState extends AbstractAppState {
@@ -93,10 +92,14 @@ public StartScreenState(SimpleApplication app){
 ----
 
 
+[IMPORTANT]
+====
+It is not sufficient to just inherit from AbstractAppState. You need to instantiate your controller class, register it with app's stateManager and then pass it to nifty. See code sample below.
+====
 
 
-[source,java]
 
+[source,java]
 ----
 
 public class TestNiftyGui extends SimpleApplication {
@@ -172,7 +175,6 @@ Here is an example that moves a panel when the startScreen opens. You place an &
 
 
 [source,xml]
-
 ----
 
 <panel height="25%" width="35%" ...>
@@ -195,7 +197,6 @@ Playing sounds using Nifty is also possible with a `playSound` effect as trigger
 
 
 [source,xml]
-
 ----
 
 <registerSound id="myclick" filename="Interface/sounds/ButtonClick.ogg" />
@@ -218,7 +219,6 @@ To pass the clickLoc as two ints, you can use the special `(int x, int y)` synta
 
 
 [source,java]
-
 ----
 
   public void clicked(int x, int y) {
@@ -231,7 +231,6 @@ In the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ screen code
 
 
 [source,xml]
-
 ----
 
 <interact onClick="clicked()"/>  
@@ -249,7 +248,6 @@ The following code sample shows how you can load several XML files into one nift
 
 
 [source,java]
-
 ----
 
 NiftyJmeDisplay niftyDisplay = new NiftyJmeDisplay(assetManager, inputManager, audioRenderer, viewPort);
@@ -275,7 +273,6 @@ The following code sample shows how you can explicitly attach several screen con
 
 
 [source,java]
-
 ----
 
 NiftyJmeDisplay niftyDisplay = NiftyJmeDisplay.newNiftyJmeDisplay(assetManager, inputManager, audioRenderer, viewPort);
@@ -293,7 +290,6 @@ By default, your Nifty XML screens use the built.in styles:
 
 
 [source,xml]
-
 ----
  <useStyles filename="nifty-default-styles.xml" /> 
 ----
@@ -302,7 +298,6 @@ But you can switch to a set of custom styles in your game project's asset direct
 
 
 [source,xml]
-
 ----
  <useStyles filename="Interface/Styles/myCustomStyles.xml" /> 
 ----
@@ -311,7 +306,6 @@ Inside myCustomStyles.xml you define styles like this:
 
 
 [source,xml]
-
 ----
 	
 <?xml version="1.0" encoding="UTF-8"?>

src/docs/asciidoc/jme3/advanced/nifty_gui_xml_layout.adoc

@@ -72,7 +72,6 @@ The following minimal XML file contains a start screen and a HUD screen. (Neithe
 
 
 [source,xml]
-
 ----
 
 <?xml version="1.0" encoding="UTF-8"?>
@@ -102,7 +101,6 @@ Delete all from the file and add following code:
 
 
 [source,xml]
-
 ----
 
 <nifty>
@@ -136,7 +134,6 @@ A panel is the inner-most container (that will contain the actual content: text,
 
 
 [source,xml]
-
 ----
 
       <panel id="panel_top" height="25%" width="75%" align="center" childLayout="center"
@@ -161,7 +158,6 @@ The following panels go into in the `hud` screen's `foreground` layer:
 
 
 [source,xml]
-
 ----
 
       <panel id="panel_left" width="80%" height="100%" childLayout="vertical" 
@@ -204,7 +200,6 @@ The link:http://hub.jmonkeyengine.org/wiki/lib/exe/fetch.php/jme3:advanced:start
 
 
 [source,xml]
-
 ----
 
     <layer id="background" childLayout="center">
@@ -217,7 +212,6 @@ The link:http://hub.jmonkeyengine.org/wiki/lib/exe/fetch.php/jme3:advanced:hud-f
 
 
 [source,xml]
-
 ----
 
     <layer id="background" childLayout="center">
@@ -230,7 +224,6 @@ In order to make the hud-frame.png independent of the screen resolution you are
 
 
 [source,xml]
-
 ----
 
     <layer id="background" childLayout="center">
@@ -244,7 +237,6 @@ In the `hud` screen's `foreground` layer, add the following image element:
 
 
 [source,xml]
-
 ----
 
         <panel id="panel_top_right2" width="100%" height="15%" childLayout="center">
@@ -264,7 +256,6 @@ The game title is a typical example of static text. In the `start` screen, add t
 
 
 [source,xml]
-
 ----
 
       <panel id="panel_top" height="25%" width="75%" align="center" childLayout="center">  
@@ -277,7 +268,6 @@ For longer pieces of static text, such as an introduction, you can use wrap=“t
 
 
 [source,xml]
-
 ----
 
       <panel id="panel_mid" height="50%" width="75%" align="center" childLayout="center">       
@@ -299,7 +289,6 @@ Before you can use any control, you must load a Control Definition first. Add th
 
 
 [source,xml]
-
 ----
 
   <useStyles filename="nifty-default-styles.xml" />
@@ -318,7 +307,6 @@ In the `hud` screen's `foreground` layer, add the following text element:
 
 
 [source,xml]
-
 ----
 
         <panel id="panel_top_right" height="100%" width="15%" childLayout="center">  
@@ -337,7 +325,6 @@ Our +++<abbr title="Graphical User Interface">GUI</abbr>+++ plan asks for two bu
 
 
 [source,xml]
-
 ----
 
         <panel id="panel_bottom_left" height="50%" width="50%" valign="center" childLayout="center">  
@@ -361,7 +348,6 @@ Your screen.xml should look like this:
 
 
 [source,xml]
-
 ----
 
 <?xml version="1.0" encoding="UTF-8"?>

src/docs/asciidoc/jme3/advanced/particle_emitters.adoc

@@ -12,7 +12,12 @@ You cannot create a 3D model for delicate things like fire, smoke, or explosions
 Creating an effect involves some trial and error to get the settings _just right_, and it's worth exploring the expressiveness of the options described below. 
 
 
-<<sdk/scene_explorer#,Scene Explorer>><<sdk#,SDK>>
+
+[TIP]
+====
+Use the <<sdk/scene_explorer#,Scene Explorer>> in the <<sdk#,SDK>> to design and preview effects.
+====
+
 
 
 image:jme3/advanced/explosion-5.png[explosion-5.png,with="150",height="100"]  image:jme3/advanced/particle.png[particle.png,with="150",height="100"]  image:jme3/beginner/beginner-effect-fire.png[beginner-effect-fire.png,with="150",height="100"] image:jme3/advanced/butterfly-particle-emitter.png[butterfly-particle-emitter.png,with="150",height="100"]
@@ -23,7 +28,6 @@ image:jme3/advanced/explosion-5.png[explosion-5.png,with="150",height="100"]  im
 
 .  Create one emitter for each effect: 
 [source,java]
-
 ----
 ParticleEmitter explosion = new ParticleEmitter(
 "My explosion effect", Type.Triangle, 30);
@@ -31,7 +35,6 @@ ParticleEmitter explosion = new ParticleEmitter(
 
 .  Attach the emitter to the rootNode and position it in the scene: 
 [source,java]
-
 ----
 rootNode.attachChild(explosion);
 explosion.setLocalTranslation(bomb.getLocalTranslation());
@@ -39,14 +42,12 @@ explosion.setLocalTranslation(bomb.getLocalTranslation());
 
 .  Trigger the effect by calling 
 [source,java]
-
 ----
 explosion.emitAllParticles()
 ----
 
 .  End the effect by calling 
 [source,java]
-
 ----
 explosion.killAllParticles()
 ----
@@ -168,7 +169,6 @@ Use the common Particle.j3md Material Definition and a texture to specify the sh
 
 
 [source,java]
-
 ----
 
     Material flash_mat = new Material(
@@ -245,7 +245,6 @@ a| image:http://jmonkeyengine.googlecode.com/svn/trunk/engine/test-data/Effects/
 == Usage Example
 
 [source,java]
-
 ----
 
     ParticleEmitter fire = new ParticleEmitter("Emitter", Type.Triangle, 30);

src/docs/asciidoc/jme3/advanced/physics.adoc

@@ -92,14 +92,12 @@ Do the following once per application to gain access to the `physicsSpace` objec
 .  Make your application extend `com.jme3.app.SimpleApplication`.
 .  Create a BulletAppState field: 
 [source,java]
-
 ----
 private BulletAppState bulletAppState;
 ----
 
 .  Initialize your bulletAppState and attach it to the state manager: 
 [source,java]
-
 ----
 public void simpleInitApp() {
     bulletAppState = new BulletAppState();
@@ -107,16 +105,20 @@ public void simpleInitApp() {
 ----
 
 
-`BulletAppState`
 
+[TIP]
+====
+In your application, you can always access the `BulletAppState` via the ApplicationStateManager: 
 
-[source,java]
 
+[source,java]
 ----
 BulletAppState bas = app.getStateManager().getState(BulletAppState.class);
 ----
 
 
+====
+
 
 
 For each Spatial that you want to be physical:
@@ -229,15 +231,19 @@ The mesh-accurate shapes can use a CollisionShapeFactory as constructor (code sa
 
 
 
+[IMPORTANT]
+====
+Pick the simplest and most applicable shape for the mesh for what you want to do: If you give a box a sphere collision shape, it will roll; if you give a ball a box collision shape, it will sit on a slope. If the shape is too big, the object will seem to float; if the shape is too small it will seem to sink into the ground. During development and debugging, you can make collision shapes visible by adding the following line after the bulletAppState initialization: 
 
 
 [source,java]
-
 ----
 bulletAppState.getPhysicsSpace().enableDebug(assetManager);
 ----
 
 
+====
+
 
 
 
@@ -245,7 +251,6 @@ bulletAppState.getPhysicsSpace().enableDebug(assetManager);
 
 *  One way of using a constructor and a Geometry's mesh for static Spatials:
 [source,java]
-
 ----
 MeshCollisionShape level_shape = 
     new MeshCollisionShape(level_geo.getMesh());
@@ -253,7 +258,6 @@ MeshCollisionShape level_shape =
 
 *  One way of using a constructor and a Geometry's mesh for dynamic Spatials:
 [source,java]
-
 ----
 HullCollisionShape shape = 
     new HullCollisionShape(katamari_geo.getMesh());
@@ -261,7 +265,6 @@ HullCollisionShape shape =
 
 *  Creating a dynamic compound shape for a whole Node and subnodes:
 [source,java]
-
 ----
 CompoundCollisionShape myComplexShape =
     CollisionShapeFactory.createMeshShape((Node) myComplexGeometry );
@@ -269,7 +272,6 @@ CompoundCollisionShape myComplexShape =
 
 *  Creating a dynamic HullCollisionShape shape (or CompoundCollisionShape with HullCollisionShapes as children) for a Geometry:
 [source,java]
-
 ----
 CollisionShape shape = 
     CollisionShapeFactory.createDynamicMeshShape(spaceCraft);
@@ -277,7 +279,6 @@ CollisionShape shape =
 
 *  An angular, non-mesh-accurate compound shape:
 [source,java]
-
 ----
 CompoundCollisionShape boxShape =
     CollisionShapeFactory.createBoxShape((Node) crate_geo);
@@ -285,7 +286,6 @@ CompoundCollisionShape boxShape =
 
 *  A round, non-mesh-accurate compound shape: 
 [source,java]
-
 ----
 SphereCollisionShape sphereShape =
     new SphereCollisionShape(1.0f);
@@ -346,27 +346,29 @@ The most commonly used physics control is RigidBodyControl.  The RigidBodyContro
 
 
 [source,java]
-
 ----
 RigidBodyControl myThing_phys = 
     new RigidBodyControl( myThing_shape , 123.0f ); // dynamic
 ----
 
 [source,java]
-
 ----
 RigidBodyControl myDungeon_phys = 
     new RigidBodyControl( myDungeon_shape , 0.0f ); // static 
 ----
 
 
+[IMPORTANT]
+====
+If you give your floor a non-zero mass, it will fall out of the scene!
+====
+
 
 
 The following creates a box Geometry with the correct default BoxCollisionShape:
 
 
 [source,java]
-
 ----
 
 Box b = new Box(1,1,1);
@@ -378,13 +380,17 @@ The following creates a MeshCollisionShape for a whole loaded (static) scene:
 
 
 [source,java]
-
 ----
 ...
 gameLevel.addControl(new RigidBodyControl(0.0f)); // explicit zero mass, implicit MeshCollisionShape
 ----
 
 
+[TIP]
+====
+Spheres and Boxes automatically fall back on the correct default CollisionShape if you do not specify a CollisionShape in the RigidBodyControl constructor. Complex static objects can fall back on MeshCollisionShapes, unless it is a Node, in which case it will become a CompoundCollisionShape containing a MeshCollisionShape
+====
+
 
 
 
@@ -395,7 +401,6 @@ For each physical Spatial in the scene:
 
 .  Add a PhysicsControl to a Spatial. 
 [source,java]
-
 ----
 myThing_geo.addControl(myThing_phys);
 ----
@@ -410,7 +415,6 @@ The PhysicsSpace is an object in BulletAppState that is like a rootNode for Phys
 
 *  Just like you add the Geometry to the rootNode, you add its PhysicsControl to the PhysicsSpace. 
 [source,java]
-
 ----
 bulletAppState.getPhysicsSpace().add(myThing_phys); 
 rootNode.attachChild(myThing_geo); 
@@ -418,14 +422,18 @@ rootNode.attachChild(myThing_geo);
 
 *  When you remove a Geometry from the scene and detach it from the rootNode, also remove the PhysicsControl from the PhysicsSpace: 
 [source,java]
-
 ----
 bulletAppState.getPhysicsSpace().remove(myThing_phys);
 myThing_geo.removeFromParent();
 ----
 
 
-_PhysicsControl__Geometry_
+
+[TIP]
+====
+You can either add the _PhysicsControl_ to the PhysicsSpace, or add the PhysicsControl to the Geometry and then add the _Geometry_ to the PhysicsSpace. jME3 understands both and the outcome is the same.
+====
+
 
 
 
@@ -441,7 +449,6 @@ When you import a model from blender, it often comes as a Node (even if it only
 
 
 [source,java]
-
 ----
 
 // Doesn't scale
@@ -630,7 +637,12 @@ setKinematic(false);
 *  You can hang kinematics up “in mid-air and attach other PhysicsControls to them using <<jme3/advanced/hinges_and_joints#,hinges and joints>>. Picture them as “air hooks for flying aircraft carriers, floating islands in the clouds, suspension bridges, swings, chains… 
 *  You can use Kinematics to create mobile remote-controlled physical objects, such as moving elevator platforms, flying blimps/airships. You have full control how Kinematics move, they never “fall or “topple over.
 
-`setLocalTranslation()``move()`<<jme3/advanced/motionpath#,MotionPath>>
+
+[IMPORTANT]
+====
+The position of a kinematic RigidBodyControl is updated automatically depending on its spatial's translation. You move Spatials with a kinematic RigidBodyControl programmatically, that means you write translation and rotation code in the update loop. You describe the motion of kinematic objects either by using methods such as `setLocalTranslation()` or `move()`, or by using a <<jme3/advanced/motionpath#,MotionPath>>. 
+====
+
 
 
 
@@ -670,7 +682,12 @@ a|Cancels out all forces (force, torque) etc and stops the motion.
 
 |===
 
-“
+
+[IMPORTANT]
+====
+It is technically possible to position PhysicsControls using setLocalTranslation(), e.g. to place them in their start position in the scene. However you must be very careful not to cause an “impossible state where one physical object overlaps with another! Within the game, you typically use the setters shown here exclusively.
+====
+
 
 
 PhysicsControls also support the following advanced features:
@@ -707,7 +724,12 @@ a|Bullet does not use the full collision shape for continuous collision detectio
 
 |===
 
-`setApplyPhysicsLocal(true)`
+
+[TIP]
+====
+ You can `setApplyPhysicsLocal(true)` for an object to make it move relatively to its local physics space. You would do that if you need a physics space that moves with a node (e.g. a spaceship with artificial gravity surrounded by zero-g space). By default, it's set to false, and all movement is relative to the world.
+====
+
 
 
 
@@ -722,7 +744,6 @@ a|Bullet does not use the full collision shape for continuous collision detectio
 *  *Eject?* If you have physical nodes jittering wildy and being ejected “for no apparent reason, it means you have created an impossible state – solid objects overlapping. This can happen when you position solid spatials too close to other solid spatials, e.g. when moving them with setLocalTranslation(). +
 *Solution:* Use the debug mode to make CollisionShapes visible and verify that CollisionShapes do not overlap. 
 [source,java]
-
 ----
 bulletAppState.getPhysicsSpace().enableDebug(assetManager);
 ----

src/docs/asciidoc/jme3/advanced/physics_listeners.adoc

@@ -31,7 +31,6 @@ The shape of the ghost depends on the CollisionShape that you gave the GhostCont
 
 
 [source,java]
-
 ----
 
 GhostControl ghost = new GhostControl(
@@ -88,7 +87,6 @@ Here's is the declaration of an examplary Physics Control that listens to ticks.
 
 
 [source,java]
-
 ----
 public class MyCustomControl
     extends RigidBodyControl implements PhysicsTickListener { ... }
@@ -104,7 +102,6 @@ The tpf value is time per frame in seconds. You can use it as a factor to time a
 
 
 [source,java]
-
 ----
 
 @override
@@ -143,7 +140,6 @@ You need to add the PhysicsCollisionListener to the physics space before collisi
 
 
 [source,java]
-
 ----
 public class MyCustomControl extends RigidBodyControl
     implements PhysicsCollisionListener {
@@ -160,7 +156,6 @@ After you identify the colliding nodes, specify the action to trigger when this
 
 
 [source,java]
-
 ----
 
     public void collision(PhysicsCollisionEvent event) {
@@ -175,6 +170,11 @@ After you identify the colliding nodes, specify the action to trigger when this
 ----
 
 
+[IMPORTANT]
+====
+Note that after the collision() method ends, the PhysicsCollisionEvent is cleared. You must get all objects and values you need within the collision() method.
+====
+
 
 
 
@@ -222,7 +222,6 @@ For example, for a click-to-select, you only care if the selection ray collides
 
 
 [source,java]
-
 ----
 myNode.getControl(RigidBodyControl.class).setCollisionGroup(PhysicsCollisionObject.COLLISION_GROUP_02);
 myNode.getControl(RigidBodyControl.class).setCollideWithGroups(PhysicsCollisionObject.COLLISION_GROUP_02);

src/docs/asciidoc/jme3/advanced/post-processor_water.adoc

@@ -15,7 +15,12 @@ image::jme3/advanced/water-post.png[water-post.png,with="",height="",align="cent
 ]
 
 
-<<jme3/advanced/water#,SimpleWaterProcessor>>
+
+[NOTE]
+====
+The SeaMonkey WaterFilter is ideal for oceans and lakes, and especially for under-water scenes. If you only need a small simple water surface, such as a water trough or a shallow fountain, the <<jme3/advanced/water#,SimpleWaterProcessor>> may already be all you need.
+====
+
 
 
 
@@ -65,7 +70,6 @@ This is how you use the water filter post-processor code in your code:
 
 
 [source,java]
-
 ----
 
 private FilterPostProcessor fpp;
@@ -96,7 +100,6 @@ If you want waves, set the water height in the update loop. We reuse the initial
 
 
 [source,java]
-
 ----
 
 private float time = 0.0f;
@@ -292,7 +295,6 @@ You should also add audio nodes with water sounds to complete the effect.
 
 
 [source,java]
-
 ----
 
 AudioNode waves = new AudioNode(assetManager, "Sounds/Environment/Ocean Waves.ogg", false);

src/docs/asciidoc/jme3/advanced/ragdoll.adoc

@@ -43,7 +43,6 @@ Since you're just creating the ragdoll for this example, all the limbs have the
 
 
 [source,java]
-
 ----
 
 private Node createLimb(float width, float height, Vector3f location, boolean rotate) {
@@ -67,7 +66,6 @@ You write a custom helper method to initialize the limbs. Look at the screenshot
 *  The shoulders and hips are _vertical_ cylinders, this is why we set the rotation to true.
 
 [source,java]
-
 ----
 
 Node shoulders = createLimb(0.2f, 1.0f, new Vector3f( 0.00f, 1.5f, 0), true);
@@ -97,7 +95,6 @@ As before, you write a small helper method. This time its purpose is to quickly
 *  Use a ConeJoint, a special joint that approximates the degree of freedom that limbs typically have. The ConeJoint constructor requires the two nodes, and the two local pivot coordinates that we just determined.
 *  Set the joints limits to allow swinging, but not twisting.
 [source,java]
-
 ----
 private PhysicsJoint join(Node A, Node B, Vector3f connectionPoint) {
         Vector3f pivotA = A.worldToLocal(connectionPoint, new Vector3f());
@@ -115,7 +112,6 @@ Use the helper method to connect all limbs with joints where they belong, at one
 
 
 [source,java]
-
 ----
 
 join(body,  shoulders, new Vector3f( 0.00f,  1.4f, 0));
@@ -140,7 +136,6 @@ We create one (non-physical) Node named ragDoll, and attach all other nodes to i
 
 
 [source,java]
-
 ----
 
 ragDoll.attachChild(shoulders);
@@ -160,7 +155,6 @@ To use the ragdoll in a scene, we attach its main node to the rootNode, and to t
 
 
 [source,java]
-
 ----
 
 rootNode.attachChild(ragDoll);
@@ -175,7 +169,6 @@ To pull the doll up, you could add an input handler that triggers the following
 
 
 [source,java]
-
 ----
 
 Vector3f upforce = new Vector3f(0, 200, 0);

src/docs/asciidoc/jme3/advanced/read_graphic_card_capabilites.adoc

@@ -14,7 +14,6 @@ You can read (and print) the capabilities of the user's graphic card using the `
 
 
 [source,java]
-
 ----
 
 Collection<Caps> caps = renderer.getCaps();
@@ -31,7 +30,6 @@ A newer graphic card has modern capabilities, for example OpenGL 2.1 and NonPowe
 
 
 [source]
-
 ----
 
 INFO: Running on jMonkeyEngine 3.0.0 
@@ -56,7 +54,6 @@ Here is an example of the capabilities of an semi-old graphic card that only sup
 
 
 [source]
-
 ----
 INFO: Running on jMonkey Engine 3 
 INFO: Using LWJGL 2.7.1
@@ -79,7 +76,6 @@ This next example is lacking `NonPowerOfTwoTextures`, this tells you that this u
 
 
 [source]
-
 ----
 
 INFO: Capabilities: [FrameBuffer, FrameBufferMRT, FrameBufferMultisample, 

src/docs/asciidoc/jme3/advanced/recast.adoc

@@ -48,7 +48,6 @@ In next code is described how the user should build navigation mesh, and query f
 
 
 [source,java]
-
 ----
 
 // Step 1. Initialize build config.
@@ -260,7 +259,6 @@ Instructions for downloading and setting it up:
 *  In Java project in class `com.jme3.ai.navigation.utils.RecastJNI.java` change +++<abbr title="Uniform Resource Locator">URL</abbr>+++ to where your build of C++ project is.
 
 [source,java]
-
 ----
 
 static {

src/docs/asciidoc/jme3/advanced/remote-controlling_the_camera.adoc

@@ -17,7 +17,6 @@ You can steer the camera using <<jme3/advanced/cinematics#,Cinematics>>:
 .  Create a Cinematic.
 .  Create a CameraNode and bind the camera object to the Cinematic. Note that we also give the camera node a name in this step. 
 [source,java]
-
 ----
 CameraNode camNode = cinematic.bindCamera("topView", cam);
 ----
@@ -25,7 +24,6 @@ CameraNode camNode = cinematic.bindCamera("topView", cam);
 .  Position the camera node in its start location.
 .  Use activateCamera() to give the control of the camera to this node. You now see the scene from this camera's point of view. For example to see through the camera node named “topView, 6 seconds after the start of the cinematic, you'd write 
 [source,java]
-
 ----
 cinematic.activateCamera(6, "topView");
 ----
@@ -35,7 +33,6 @@ cinematic.activateCamera(6, "topView");
 === Code Sample
 
 [source,java]
-
 ----
 
 flyCam.setEnabled(false);

src/docs/asciidoc/jme3/advanced/save_and_load.adoc

@@ -14,7 +14,12 @@ Spatials (that is Nodes and Geometries) can contain audio and light nodes, parti
 The jMonkeyEngine's binary file format is called `.j3o`. You can convert, view and edit .j3o files and their materials in the jMonkeyEngine <<sdk#,SDK>> and compose scenes (this does not include editing meshes). For the conversion, you can either use the BinaryExporters, or a context menu in the SDK.
 
 
-`com.jme3.export.Savable`<<jme3/advanced/spatial#,spatial's user data>>“
+
+[IMPORTANT]
+====
+The jMonkeyEngine's serialization system is the `com.jme3.export.Savable` interface. JME3's BinaryExporter can write standard Java objects, JME3 objects, and primitive data types that are included in a <<jme3/advanced/spatial#,spatial's user data>>. If you use custom game data classes, see below how to make them “Savable.
+====
+
 
 
 There is also a com.jme3.export.xml.XMLExporter and com.jme3.export.xml.XMLImporter that similarly converts jme3 spatials to an XML format. But you wouldn't use that to load models at runtime (quite slow).
@@ -31,11 +36,15 @@ There is also a com.jme3.export.xml.XMLExporter and com.jme3.export.xml.XMLImpor
 The following example overrides `stop()` in SimpleApplication to save the rootNode to a file when the user quits the application. The saved rootNode is a normal .j3o binary file that you can open in the <<sdk#,SDK>>.
 
 
-`assets`
 
+[WARNING]
+====
+Note that when you save a model that has textures, the references to those textures are stored as absolute paths, so when loading the j3o file again, the textures have to be accessible at the exact location (relative to the assetmanager root, by default the `assets` directory) they were loaded from. This is why the SDK manages the conversion on the project level.
+====
 
-[source,java]
 
+
+[source,java]
 ----
 
   /* This is called when the user quits the app. */
@@ -60,7 +69,6 @@ The following example overrides `simpleInitApp()` in SimpleApplication to load `
 
 
 [source,java]
-
 ----
   @Override
   public void simpleInitApp() {
@@ -73,7 +81,12 @@ The following example overrides `simpleInitApp()` in SimpleApplication to load `
    
 ----
 
-–
+
+[TIP]
+====
+Here you see why we save user data inside spatials – so it can be saved and loaded together with the .j3o file. If you have game data outside Spatials, you have to remember to save() and load(), and get() and set() it yourself.
+====
+
 
 
 
@@ -94,7 +107,6 @@ So every time you create a custom Control or custom user data class, remember to
 
 
 [source,java]
-
 ----
 
 import com.jme3.export.InputCapsule;
@@ -146,4 +158,9 @@ To make a custom class savable:
 
 
 
+[IMPORTANT]
+====
+As with all serialization, remember that if you ever change data types in custom classes, the updated read() methods will no longer be able to read your old files. Also there has to be a constructor that takes no Parameters.
+====
+
 

src/docs/asciidoc/jme3/advanced/screenshots.adoc

@@ -14,7 +14,6 @@ You activate this feature as follows in your simpleInitApp() method:
 
 
 [source,java]
-
 ----
 
 ScreenshotAppState screenShotState = new ScreenshotAppState();

src/docs/asciidoc/jme3/advanced/shape.adoc

@@ -89,6 +89,11 @@ To add a shape to the scene:
 .  Attach the Geometry to the rootNode to make it visible.
 
 
+[TIP]
+====
+Create one static shape as mesh and use it in several geometries, or clone() the geometries.
+====
+
 
 
 
@@ -113,43 +118,36 @@ Create the Mesh shape:
 
 
 [source,java]
-
 ----
 Sphere mesh = new Sphere(32, 32, 10, false, true);
 ----
 
 [source,java]
-
 ----
 Dome mesh = new Dome(Vector3f.ZERO, 2, 4, 1f,false); // Pyramid
 ----
 
 [source,java]
-
 ----
 Dome mesh = new Dome(Vector3f.ZERO, 2, 32, 1f,false); // Cone
 ----
 
 [source,java]
-
 ----
 Dome mesh = new Dome(Vector3f.ZERO, 32, 32, 1f,false); // Small hemisphere
 ----
 
 [source,java]
-
 ----
 Dome mesh = new Dome(Vector3f.ZERO, 32, 32, 1000f,true); // SkyDome
 ----
 
 [source,java]
-
 ----
 PQTorus mesh = new PQTorus(5,3, 2f, 1f, 32, 32); // Spiral torus
 ----
 
 [source,java]
-
 ----
 PQTorus mesh = new PQTorus(3,8, 2f, 1f, 32, 32); // Flower torus
 ----
@@ -158,7 +156,6 @@ Use one of the above examples together with the following geometry in a scene:
 
 
 [source,java]
-
 ----
 
 Geometry geom = new Geometry("A shape", mesh); // wrap shape into geometry

src/docs/asciidoc/jme3/advanced/sky.adoc

@@ -22,7 +22,6 @@ Adding a sky is extremely easy using the `com.jme3.util.SkyFactory`.
 
 
 [source,java]
-
 ----
 
 rootNode.attachChild(SkyFactory.createSky(

src/docs/asciidoc/jme3/advanced/softbody.adoc

@@ -7,7 +7,12 @@
 ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 
-link:http://hub.jmonkeyengine.org/t/bullet-softbody-in-jme3-1/33110[http://hub.jmonkeyengine.org/t/bullet-softbody-in-jme3-1/33110]
+
+[WARNING]
+====
+Writing in progress, checkout the forum for additional infos link:http://hub.jmonkeyengine.org/t/bullet-softbody-in-jme3-1/33110[http://hub.jmonkeyengine.org/t/bullet-softbody-in-jme3-1/33110]
+====
+
 what is a soft body ?
 
 
@@ -36,7 +41,6 @@ The dynamics libraries for softbody (.so , .dll …) isn't (yet) prebuild for yo
 == Simple Example
 
 [source,java]
-
 ----
 
 public void simpleInitApp() {
@@ -99,7 +103,6 @@ More informations on creating <<jme3/advanced/custom_meshes#,custom meshes>>.
 ==== Example
 
 [source,java]
-
 ----
 
 Mesh ropeMesh = new Mesh();
@@ -133,7 +136,6 @@ Once you have a Line Mesh, you can do as follow :
 
 
 [source,java]
-
 ----
 
 Geometry t = new Geometry("softRope", ropeMesh);
@@ -150,7 +152,6 @@ Adding a anchors to a soft body require to specify the SoftBody's node and the R
 
 
 [source,java]
-
 ----
 
 soft.appendAnchor(nodeId, rigid);
@@ -164,13 +165,17 @@ An anchor bind a SoftBody's node (or Vertex) to a RigidBody, the node will be at
 
 
 
+[WARNING]
+====
+ Anchors are not yet Serialized 
+====
+
 
 
 
 ==== Example
 
 [source,java]
-
 ----
 
 Geometry t = new Geometry("softRope", ropeMesh);
@@ -197,7 +202,6 @@ Anchors can be removed as below. Note that you have to keep the node and RigidBo
 
 
 [source,java]
-
 ----
 
 soft.removeAnchor(8,rigid);
@@ -211,13 +215,17 @@ Joints require SoftBodies with Clusters ( see generateClusters(int k) ).
 
 
 
+[WARNING]
+====
+ joint don't use values pivotA &amp; pivotB (not yet) 
+====
+
 
 
 
 ===== LinearJoint
 
 [source,java]
-
 ----
 
 public SoftLinearJoint(Vector3f position, PhysicsSoftBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB);
@@ -229,7 +237,6 @@ public SoftLinearJoint(Vector3f position, PhysicsSoftBody nodeA, PhysicsSoftBody
 ===== AngularJoint
 
 [source,java]
-
 ----
 
 public SoftAngularJoint(Vector3f axis, PhysicsSoftBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB);
@@ -244,7 +251,6 @@ public SoftAngularJoint(Vector3f axis, PhysicsSoftBody nodeA, PhysicsSoftBody no
 ===== LinearJoint
 
 [source,java]
-
 ----
 
 Box box = new Box(3f, 1f, 3f);
@@ -272,7 +278,6 @@ softBodyAppState.getPhysicsSoftSpace().add(joint);
 ===== AngularJoint
 
 [source,java]
-
 ----
 
 Box box = new Box(1f, 1f, 1f);

src/docs/asciidoc/jme3/advanced/spatial.adoc

@@ -62,7 +62,12 @@ a| rootNode, guiNode, audioNode, a custom grouping node such as vehicleNode or s
 
 |===
 
-`+++<strike>Spatial s = new Spatial();</strike>+++`“`Spatial`_cast_
+
+[IMPORTANT]
+====
+You never create a Spatial with `+++<strike>Spatial s = new Spatial();</strike>+++`! A Spatial is an abstract concept, like a mammal (there is no actual creature called “mammal walking around here). You create either a com.jme3.scene.Node or com.jme3.scene.Geometry instance. Some methods, however, require a `Spatial` type as argument: This is because they are able to accept both Nodes and Geometries as arguments. In this case, you simply _cast_ a Node or Geometry to Spatial.
+====
+
 
 
 
@@ -90,7 +95,12 @@ The second use case is: When you load a model using `loadModel()` from the Asset
 Usually there is no need to manually use any of the `clone()` methods on models. Using the <<jme3/advanced/asset_manager#,Asset Manager>>'s `loadModel()` method will automatically do the right thing for your models.
 
 
-“`Box()`_voxelization_
+
+[NOTE]
+====
+“Box worlds are not made up of statically cloned `Box()` shapes, this would still be too slow for large worlds. To learn how to make real fast box worlds, search the web for _voxelization_ techniques.
+====
+
 
 
 
@@ -99,14 +109,18 @@ Usually there is no need to manually use any of the `clone()` methods on models.
 You can include custom user data –that is, custom Java objects and methods– in Nodes and Geometries. This is very useful for maintaining information about a game element, such as health, budget, ammunition, inventory, equipment, etc for players, or landmark locations for terrains, and much more. 
 
 
-`Node``Geometry`<<jme3/advanced/custom_controls#,Custom Controls>>`Node``Geometry``setUserData()`
+
+[IMPORTANT]
+====
+You want to add custom accessor methods to a spatial? Do not extend `Node` or `Geometry`, use <<jme3/advanced/custom_controls#,Custom Controls>> instead. You want to add custom fields to a spatial? Do not extend `Node` or `Geometry`, use the built-in `setUserData()` method instead. Where ever the Spatial is accessible, you can easily access the object's class fields (user data) and accessors (control methods) this way. 
+====
+
 
 
 This first example adds an integer field named `health` to the Spatial `playerNode`, and initializes it to 100.
 
 
 [source,java]
-
 ----
 playerNode.setUserData("health", 100);
 ----
@@ -115,7 +129,6 @@ The second example adds a set of custom accessor methods to the player object. Y
 
 
 [source,java]
-
 ----
 playerNode.addControl(new PlayerControl());
 ----
@@ -124,7 +137,6 @@ In your PlayerControl() class, you define custom methods that set and get your u
 
 
 [source,java]
-
 ----
 
 public int getHealth() {
@@ -140,7 +152,6 @@ Elsewhere in your code, you can access this data wherever you have access to the
 
 
 [source,java]
-
 ----
 
 health = playerNode.getControl(PlayerControl.class).getHealth();
@@ -157,7 +168,6 @@ This is how you list all data keys that are already defined for one Spatial:
 
 
 [source,java]
-
 ----
 for(String key : spatial.getUserDataKeys()){
     System.out.println(spatial.getName()+"'s keys: "+key);
@@ -178,7 +188,6 @@ In the following example, the Node `house` is the loaded model. The sub-meshes i
 
 
 [source,java]
-
 ----
 
 Geometry submesh = (Geometry) houseScene.getChild("door 12");
@@ -209,7 +218,6 @@ Example:
 
 
 [source,java]
-
 ----
 material.getAdditionalRenderState().setFaceCullMode(FaceCullMode.FrontAndBack);
 ----
@@ -229,7 +237,6 @@ Example:
 
 
 [source,java]
-
 ----
 spatial.setCullHint(CullHint.Never); // always drawn
 ----

src/docs/asciidoc/jme3/advanced/statsview.adoc

@@ -19,7 +19,6 @@ The StatsView + FpsView look like this example:
 
 
 [source]
-
 ----
 
 FrameBuffers (M) = 2
@@ -46,7 +45,6 @@ You switch the StatsView on an off in the simpleInitApp() method by setting a bo
 
 
 [source,java]
-
 ----
  
 setDisplayFps(false);       // to hide the FPS
@@ -94,6 +92,11 @@ Keep an eye on FPS and the StatsView and find out which element has the biggest
 == How to Interpret The Statistics
 
 
+[IMPORTANT]
+====
+To interpret the numbers correctly, consider that the 14 lines of text themselves already count as 14 objects with 914 vertices. You need to subtract these values from the totals for smaller performance experiments.
+====
+
 
 
 What do you want to avoid?

src/docs/asciidoc/jme3/advanced/steer_behaviours.adoc

@@ -70,7 +70,12 @@ All the behaviours extend from the `AbstractSteeringBehavior` class.
 Create instances from the steer behavior classes, They are located in the `com.jme3.ai.agents.behaviors.npc.steering` package. 
 
 
-If we want to add more than one steer behavior, we need to create a container: `SimpleMainBehavior`
+If we want to add more than one steer behavior, we need to create a container: 
+[WARNING]
+====
+If you add more than one steer behavior to a `SimpleMainBehavior` it will cause problems in the rotation of the agents. 
+====
+
 
 [cols="2", options="header"]
 |===
@@ -90,7 +95,6 @@ Once we know which container fits better for our agent, We create a new instance
 
 
 [source,java]
-
 ----
 
 SimpleMainBehaviour mainBehavior = new SimpleMainBehavior(myAgent);
@@ -104,10 +108,14 @@ myAgent.setMainBehavior(mainBehavior);
 ----
 
 
+[NOTE]
+====
+Note that you can have nested containers, like is shown in the following example:
+====
 
 
-[source,java]
 
+[source,java]
 ----
 
 SimpleMainBehaviour mainBehavior = new SimpleMainBehavior(myAgent);
@@ -135,6 +143,16 @@ To assign priority layers add behaviors with the following function:
 ....
 
 
+[TIP]
+====
+To optimize the process speed add the behaviors with the lowest priority first. 
+====
+
+
+[NOTE]
+====
+The layer and the min length to consider the behavior invalid are 0 by default.
+====
 
 
 
@@ -151,7 +169,6 @@ Example:
 
 
 [source,java]
-
 ----
 
     Plane horizontalPlane = new Plane(new Vector3f(0,1,0), 0);
@@ -172,7 +189,6 @@ The responsible for the agent's acceleration is the vector returned in the `calc
 
 
 [source,java]
-
 ----
 
     @Override
@@ -190,7 +206,6 @@ In addition, you can change a brake factor which will reduce the resultant veloc
 
 
 [source,java]
-
 ----
 
     @Override
@@ -202,6 +217,16 @@ In addition, you can change a brake factor which will reduce the resultant veloc
 ----
 
 
+[WARNING]
+====
+The braking force must be a float contained in the [0,1] interval
+====
+
+
+[NOTE]
+====
+0 means the maximum braking force and 1 No braking force
+====
 
 
 
@@ -215,7 +240,6 @@ Example:
 
 
 [source,java]
-
 ----
 
     public class CustomSteeringExceptions extends SteeringExceptions  {
@@ -230,7 +254,6 @@ Example:
 ----
 
 [source,java]
-
 ----
 
     public SteerBehaviorConstructor(Agent agent, int value, Spatial spatial) {

src/docs/asciidoc/jme3/advanced/swing_canvas.adoc

@@ -37,7 +37,6 @@ The camera's default behaviour in SimpleApplication is to capture the mouse, whi
 
 
 [source,java]
-
 ----
 
 public void simpleInitApp() {
@@ -61,7 +60,6 @@ In the SwingCanvasTest's main() method, create a queued runnable(). It will cont
 
 
 [source,java]
-
 ----
 
   public static void main(String[] args) {
@@ -75,6 +73,11 @@ In the SwingCanvasTest's main() method, create a queued runnable(). It will cont
 ----
 
 
+[IMPORTANT]
+====
+Note that you have to use app.enqueue() when modifying objects in the scene from the AWT Event Queue like you have to use java.awt.EventQueue.invokeLater() from other threads (e.g. the update loop) when changing swing elements. This can get hairy quickly if you don’t have a proper threading model planned so you might want to use NiftyGUI as it is embedded in the update loop thread and is also cross-platform compatible (e.g. android etc.).
+====
+
 
 
 
@@ -87,7 +90,6 @@ Specify the com.jme3.system.AppSettings so jME knows the size of the Swing panel
 
 
 [source,java]
-
 ----
 AppSettings settings = new AppSettings(true);
 settings.setWidth(640);
@@ -98,7 +100,6 @@ We create our canvas application SwingCanvasTest, and give it the settings. We m
 
 
 [source,java]
-
 ----
 SwingCanvasTest canvasApplication = new SwingCanvasTest();
 canvasApplication.setSettings(settings);
@@ -120,7 +121,6 @@ Which ever you do, let's call the jFrame `window`.
 
 
 [source,java]
-
 ----
 JFrame window = new JFrame("Swing Application");
 window.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
@@ -133,7 +133,6 @@ The important step is to add() the canvas component into the panel, like all the
 
 
 [source,java]
-
 ----
 JPanel panel = new JPanel(new FlowLayout()); // a panel
 // add all your Swing components ...
@@ -148,7 +147,6 @@ OK, the jFrame and the panel are ready. We add the panel into the jFrame, and pa
 
 
 [source,java]
-
 ----
 
 window.add(panel);
@@ -160,7 +158,6 @@ Remember that we haven't called start() on the jME appliation yet? For the canva
 
 
 [source,java]
-
 ----
 canvasApplication.startCanvas();
 ----

src/docs/asciidoc/jme3/advanced/terrain.adoc

@@ -85,7 +85,12 @@ When you “slap a texture on a mesh, the whole mesh looks the same. For big mes
 The default material for TerraMonkey is TerrainLighting.j3md. This material combines several texture maps to produce the final custom texture. Remember, Diffuse Maps are the main textures that define the look; optionally, each Diffuse Map can be enhanced with a Normal Map; Alpha Maps describe the opacity of each Diffuse Map used (one color –red, green, blue, or alpha– stands for one Diffuse Map's opacity); Glow and Specular Maps define optional effects. 
 
 
-link:http://jmonkeyengine.org/wiki/doku.php/sdk:terrain_editor[create and edit Splat Textures for terrains visually in the jMonkeyEngine SDK]
+
+[IMPORTANT]
+====
+We recommend to link:http://jmonkeyengine.org/wiki/doku.php/sdk:terrain_editor[create and edit Splat Textures for terrains visually in the jMonkeyEngine SDK], and not do it manually. If you are simply curious about how the SDK's terrain texture plugin works, or if you indeed want to generate materials manually, then read on for the implementation details.
+====
+
 
 
 Here are the names of TerrainLighting.j3md's material properties:
@@ -164,7 +169,6 @@ First, we load our textures and the heightmap texture for the terrain
 
 
 [source,java]
-
 ----
 
 // Create material from Terrain Material Definition
@@ -195,7 +199,6 @@ We create the heightmap from the `heightMapImage`.
 
 
 [source,java]
-
 ----
 
 AbstractHeightMap heightmap = null;
@@ -212,7 +215,6 @@ Next we create the actual terrain.
 *  It uses the heightmap to generate the height values.
 
 [source,java]
-
 ----
 
 terrain = new TerrainQuad("terrain", 65, 513, heightmap.getHeightMap());
@@ -230,7 +232,6 @@ PS: As an alternative to an image-based height map, you can also generate a Hill
 
 
 [source,java]
-
 ----
 
 heightmap = new HillHeightMap(1025, 1000, 50, 100, (byte) 3);

src/docs/asciidoc/jme3/advanced/terrain_collision.adoc

@@ -18,7 +18,6 @@ This tutorial expands the HelloTerrain tutorial and makes the terrain solid. You
 == Sample Code
 
 [source,java]
-
 ----
 package jme3test.helloworld;
 
@@ -241,7 +240,6 @@ Read <<jme3/beginner/hello_collision#,Hello Collision>> for details of the follo
 .  The custom `setUpKeys()` method loads your reconfigured input handlers. They now don't just walk blindly, but calculate the `walkDirection` vector that we need for collision detection.
 .  `simpleUpdate()` uses the `walkDirection` vector and makes the character walk, while taking obstacles and solid walls/floor into account. 
 [source,java]
-
 ----
 player.setWalkDirection(walkDirection);
 ----
@@ -259,7 +257,6 @@ Here are the changed parts to combine the two:
 .  Add the control to the `terrain` to make it physical.
 
 [source,java]
-
 ----
 /** 6. Add physics: */ 
     terrain.addControl(new RigidBodyControl(0));  
@@ -270,7 +267,6 @@ You attach the `terrain` and the first-person `player` to the rootNode, and to t
 
 
 [source,java]
-
 ----
 
     bulletAppState.getPhysicsSpace().add(terrain);

src/docs/asciidoc/jme3/advanced/texture_atlas.adoc

@@ -91,6 +91,11 @@ You reference textures by their *asset key name*, this is what their “id is. F
 *  The TextureAtlas lets you change the texture coordinates of a mesh or geometry to point at the new locations of its texture inside the atlas (if the texture exists inside the atlas). ??
 
 
+[IMPORTANT]
+====
+Note that models that use texture coordinates outside the 0-1 range (that is, they use repeating/wrapping textures) do not work correctly as their new coordinates leak into other parts of the atlas and thus display other textures instead of repeating the texture!
+====
+
 
 
 
@@ -100,7 +105,6 @@ Use `makeAtlasBatch` to turn several geometries that are loaded from a j3o file
 
 
 [source,java]
-
 ----
 
  // scene contains many geometries ared attached to one node:
@@ -115,7 +119,6 @@ Create a texture atlas and change the texture coordinates of one geometry:
 
 
 [source,java]
-
 ----
 
  Node scene = assetManager.loadModel("Scenes/MyScene.j3o");

src/docs/asciidoc/jme3/advanced/traverse_scenegraph.adoc

@@ -39,7 +39,6 @@ For each search, you create a `com.jme3.scene.SceneGraphVisitorAdapter` that def
 
 
 [source,java]
-
 ----
 
 SceneGraphVisitor visitor = new SceneGraphVisitor() {

src/docs/asciidoc/jme3/advanced/vehicles.adoc

@@ -67,7 +67,6 @@ Every physical object must have a collision shape, that we prepare first. For th
 
 
 [source,java]
-
 ----
 
 CompoundCollisionShape compoundShape = new CompoundCollisionShape();
@@ -79,7 +78,6 @@ BoxCollisionShape box = new BoxCollisionShape(new Vector3f(1.2f, 0.5f, 2.4f));
 
 
 [source,java]
-
 ----
 compoundShape.addChildShape(box, new Vector3f(0, 1, 0));
 ----
@@ -88,7 +86,6 @@ Any kind of geometry can make up the visible part of the vehicle, here we use a
 
 
 [source,java]
-
 ----
 Node vehicleNode=new Node("vehicleNode");
 vehicle = new VehicleControl(compoundShape, 400);
@@ -99,7 +96,6 @@ We initialize the Vehicle Control with the compound shape, and set its mass to a
 
 
 [source,java]
-
 ----
 vehicle = new VehicleControl(compoundShape, 400);
 ----
@@ -108,7 +104,6 @@ Finally we add the behaviour (VehicleControl) to the visible Geometry (node).
 
 
 [source,java]
-
 ----
 vehicleNode.addControl(vehicle);
 ----
@@ -117,7 +112,6 @@ We configure the physical properties of the vehicle's suspension: Compresion, Da
 
 
 [source,java]
-
 ----
 float stiffness = 60.0f;//200=f1 car
 float compValue = .3f; //(should be lower than damp)
@@ -152,7 +146,6 @@ We initialize a few variables that we will reuse when we add the four wheels. yO
 
 
 [source,java]
-
 ----
 
 Vector3f wheelDirection = new Vector3f(0, -1, 0);
@@ -169,7 +162,6 @@ We create a Cylinder mesh shape that we use to create the four visible wheel geo
 
 
 [source,java]
-
 ----
 Cylinder wheelMesh = new Cylinder(16, 16, radius, radius * 0.6f, true);
 ----
@@ -178,7 +170,6 @@ For each wheel, we create a Node and a Geometry. We attach the Cylinder Geometry
 
 
 [source,java]
-
 ----
 
 Node node1 = new Node("wheel 1 node");
@@ -196,7 +187,6 @@ The three next wheels are created in the same fashion, only the offsets are diff
 
 
 [source,java]
-
 ----
 
 ...
@@ -215,7 +205,6 @@ Attach the wheel Nodes to the vehicle Node to group them, so they move together.
 
 
 [source,java]
-
 ----
 
 vehicleNode.attachChild(node1);
@@ -229,7 +218,6 @@ As always, attach the vehicle Node to the rootNode to make it visible, and add t
 
 
 [source,java]
-
 ----
 
 rootNode.attachChild(vehicleNode);
@@ -259,7 +247,6 @@ In the ActionListener, we implement the actions that control the vehicle's direc
 `vehicle.applyImpulse(jumpForce, Vector3f.ZERO);`
 
 [source,java]
-
 ----
 public void onAction(String binding, boolean value, float tpf) {
   if (binding.equals("Lefts")) {
@@ -299,7 +286,6 @@ For your reference, this is how we initialized the constants for this example:
 
 
 [source,java]
-
 ----
 
 private final float accelerationForce = 1000.0f;

src/docs/asciidoc/jme3/advanced/video.adoc

@@ -28,7 +28,12 @@ link:http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/op
 link:http://www.xuggle.com/xuggler[Xuggler]
 
 
-+++<abbr title="Application Programming Interface">API</abbr>+++
+
+[WARNING]
+====
+This +++<abbr title="Application Programming Interface">API</abbr>+++ is deprecated.
+====
+
 
 
 jMonkeyEngine supports Jheora Ogg video (`com.jme3.video`).
@@ -41,7 +46,6 @@ You create either a file inputstream to load the video from your hard drive:
 
 
 [source,java]
-
 ----
 FileInputStream  fis = new FileInputStream("E:\\my_bunny.ogg");
 ----
@@ -50,7 +54,6 @@ Or you stream the video live from a web location:
 
 
 [source,java]
-
 ----
 InputStream fis = new URL("http://server/my_video.ogg").openStream();
 ----
@@ -60,7 +63,6 @@ Here is an example of video streaming in context:
 
 
 [source,java]
-
 ----
 
     private void createVideo(){
@@ -84,7 +86,6 @@ Use the simpleUpdate() method to play the audio:
 
 
 [source,java]
-
 ----
 
     @Override
@@ -166,7 +167,6 @@ Helper Methods:
 
 
 [source,java]
-
 ----
 
     private void drawFrame(VFrame frame){
@@ -185,7 +185,6 @@ Helper Methods:
 ----
 
 [source,java]
-
 ----
 
     private void waitNanos(long time){

src/docs/asciidoc/jme3/advanced/walking_character.adoc

@@ -14,7 +14,12 @@ In the <<jme3/beginner/hello_collision#,Hello Collision>> tutorial and the link:
 Other games however require a third-person perspective of the character: In these cases you use a CharacterControl on a Spatial. This example also shows how to set up custom navigation controls, so you can press WASD to make the third-person character walk; and how to implement dragging the mouse to rotate.
 
 
-+++<abbr title="Application Programming Interface">API</abbr>++++++<abbr title="Application Programming Interface">API</abbr>+++
+
+[WARNING]
+====
+Some details on this page still need to be updated from old CharacterControl +++<abbr title="Application Programming Interface">API</abbr>+++ to BetterCharacterControl +++<abbr title="Application Programming Interface">API</abbr>+++.
+====
+
 
 
 
@@ -43,7 +48,6 @@ This code sample creates a simple upright Character:
 
 
 [source,java]
-
 ----
 
 // Load any model
@@ -62,7 +66,6 @@ To use the BetterCharacterControl, you may load your character like this:
 
 
 [source,java]
-
 ----
 
 // Load any model
@@ -90,7 +93,12 @@ rootNode.attachChild(playerNode); // add wrapper to root
 
 ----
 
-“<<jme3/advanced/physics_listeners#,collision listener>>
+
+[IMPORTANT]
+====
+The BulletPhysics CharacterControl only collides with “real PhysicsControls (RigidBody). It does not detect collisions with other CharacterControls! If you need additional collision checks, add GhostControls to your characters and create a custom <<jme3/advanced/physics_listeners#,collision listener>> to respond. (The JME3 team may implement a better CharacterControl one day.)
+====
+
 
 
 A CharacterControl is a special kinematic object with restricted movement. CharacterControls have a fixed “upward axis, this means they do not topple over when walking over an obstacle (as opposed to RigidBodyControls), which simulates a being's ability to balance upright. A CharacterControl can jump and fall along its upward axis, and it can scale steps of a certain height/steepness.
@@ -133,7 +141,6 @@ For best practices on how to use `setWalkDirection()`, see the Navigation Inputs
 === Code Skeleton
 
 [source,java]
-
 ----
 public class WalkingCharacterDemo extends SimpleApplication
         implements ActionListener, AnimEventListener {
@@ -175,7 +182,6 @@ To create a walking character:
 === Activate Physics
 
 [source,java]
-
 ----
 
 private BulletAppState bulletAppState;
@@ -196,7 +202,6 @@ In the simpleInitApp() method you initialize the scene and give it a MeshCollisi
 
 
 [source,java]
-
 ----
 
 public void simpleInitApp() {
@@ -211,7 +216,6 @@ In a real game, you would load a scene model here instead of a test world. You c
 
 
 [source,java]
-
 ----
 
 private Node gameLevel;
@@ -238,7 +242,6 @@ Also, add a light source to be able to see the scene.
 
 
 [source,java]
-
 ----
 
   AmbientLight light = new AmbientLight();
@@ -261,7 +264,6 @@ You create an animated model, such as Oto.mesh.xml.
 .  Attach the visible model to the rootNode.
 
 [source,java]
-
 ----
 
 private CharacterControl character;
@@ -280,7 +282,12 @@ public void simpleInitApp() {
 
 ----
 
-*Did you know?*
+
+[TIP]
+====
+*Did you know?* A CapsuleCollisionShape is a cylinder with rounded top and bottom. A capsule rotated upright is a good collision shape for a humanoid character since its roundedness reduces the risk of getting stuck on obstacles.
+====
+
 
 
 
@@ -290,7 +297,6 @@ Create several AnimChannels, one for each animation that can happen simultaneous
 
 
 [source,java]
-
 ----
 
 private AnimChannel animationChannel;
@@ -317,7 +323,6 @@ The attackChannel only controls one arm, while the walking channels controls the
 === Add ChaseCam / CameraNode
 
 [source,java]
-
 ----
 
 private ChaseCamera chaseCam;
@@ -339,7 +344,6 @@ Configure custom key bindings for WASD keys that you will use to make the charac
 
 
 [source,java]
-
 ----
 
 // track directional input, so we can walk left-forward etc
@@ -367,7 +371,6 @@ Respond to the key bindings by setting variables that track in which direction y
 
 
 [source,java]
-
 ----
 
 @Override
@@ -396,7 +399,6 @@ The player can attack and walk at the same time. `Attack()` is a custom method t
 
 
 [source,java]
-
 ----
 
 private void attack() {
@@ -413,7 +415,6 @@ The variable `airTime` tracks how long the character is off the ground (e.g. whe
 
 
 [source,java]
-
 ----
 
 private Vector3f walkDirection = new Vector3f(0,0,0); // stop
@@ -465,7 +466,6 @@ This method resets the walk animation.
 
 
 [source,java]
-
 ----
 
 public void onAnimCycleDone(AnimControl control, AnimChannel channel, String animName) {