share first result of conversion from dokuwiki to asciidoc

src/docs/asciidoc/bsd_license.adoc

@@ -0,0 +1,36 @@
+
+
+== jME's BSD License
+
+[source]
+----
+Copyright (c) 2003-2012 jMonkeyEngine
+All rights reserved.
+ 
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+ 
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+ 
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+ 
+Neither the name of 'jMonkeyEngine' nor the names of its contributors 
+may be used to endorse or promote products derived from this software 
+without specific prior written permission.
+ 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+----

src/docs/asciidoc/bugtest.adoc

@@ -0,0 +1,11 @@
+
+
+= wiki bug test page
+
+askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh
+*askjdhaskjdh akjdh lkjskal akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh*
+khjg akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh
+ii askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh
+lkjhg akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh
+akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh askjdhaskjdh akjdh akjdsh akjdhakjsdh 
+

src/docs/asciidoc/choose-jme2-or-jme3.adoc

@@ -0,0 +1,77 @@
+
+
+= "Which should I choose? jME2 or jME3?"
+
+It is is one of the most common questions on the jME board, hence this wiki page is dedicated to answering it in full. For further insight on features, please refer to this <<compare-jme2-jme3#, comparison between jME2 and jME3>>.
+
+
+If you are still not sure about your choice, we'll be happy to answer your questions on the forum. Many have asked before though, so please start out with a couple search terms like 'jme2 and jme3' and you might find that your question has been answered already.
+
+
+
+= Why choose jME3?
+
+
+== Current- & next-generation graphics
+
+From the beginning, jME3 was designed with modern principles and hardware in mind. Being shader based and only supporting OpenGL 2 or higher, jME3 is meant for the higher end of today's computers, and what's yet to come. OpenGL 1 support is limited to the basics of displaying textured models.
+
+
+
+== Actively developed
+
+As opposed to it's legacy counterpart, jME3 is very actively developed by a team of core developers and a huge community of contributors. Any aspect of jME3 can be brought up for debate at any time.
+P.S. The earlier you get involved the greater the chance you can have a changing impact on the project.
+
+
+
+== Ever-improving documentation
+
+The majority of new docs created today are documentation for jMonkeyEngine3. While naturally part of a grand community effort, these docs benefit greatly from the added support and continued iteration by core team members.
+
+
+
+== jMonkeyEngine SDK
+
+With jMonkeyEngine <<sdk#,SDK>>, jME3 is the first jME version with a dedicated IDE for application development, deployment, asset management and composition tools.
+
+
+
+== Broad Featureset
+
+A major design goal for jME3 is “no game-dev essential left behind. Straight out of the box we aim to deliver all the basics you need to practically prototype any type of game: Physics, networking, terrain and so on, all bundled, but not forced. You can always replace any feature that doesn't match your game's requirement with a custom solution of your own making.
+
+
+
+== We'll be so happy to have you!
+
+Naturally we are thrilled every time someone has decided to adopt jME3 for their [game-] development needs. Prospectively speaking, this means more testing, more commits, more buzz, more projects, more innovation; better community.
+
+
+
+= Why choose jME2?
+
+
+== Stability right now
+
+jME2 has been deemed stable since 2009, with no major feature additions or reworks since 2008. Although there are plans for a final point version release (2.1), jME2 is practically in complete feature freeze.
+
+
+
+== Support for low-end computers
+
+jME2 fully supports OpenGL 1, while jME3 does not. Coupled with careful programming this means you can achieve very low hardware requirements for your project.
+
+
+
+== Community Tools
+
+Well written utilities like SceneMonitor and SceneWorker greatly enrich the engine's toolset.
+
+
+
+== Thoroughly documented
+
+There are literally hundreds of pages of documentation for jMonkeyEngine 2.0, detailing development practices with the engine from beginners' levels through intermediate to advanced. Do note however that as jME3 grows more popular this documentation will be maintained by the community alone (see 'Ever-improving documentation' in the jME3 section below).
+
+<tags><tag target="about" /></tags>

src/docs/asciidoc/compare-jme2-jme3.adoc

@@ -0,0 +1,147 @@
+
+
+= Technical comparison between jME2 and jME3
+
+
+== Shaders?
+
+*  jME3: Shaders are integrated in the core and material system. JME3 supports shader libraries and permutations through defines. User-friendly post-processor filters, scene processors, and <<jme3/advanced/jme3_shadernodes#,shader node system>> (you don't need to know shaders to be able to use them).
+**  jME2: Full access to shader support through a RenderState, requires user to know and understand shaders. No support for libraries or permutations.
+
+
+== Resource management?
+
+*  jME3: Integrated in core. All data loaded from files is cached inside AssetManager. User customizable. Supports threaded loading. Can load from ZIP/JAR files on the local harddrive and on an HTTP server.
+*  jME2: Only textures are managed in TextureManager. ResourceLocatorTool is used for locating resources.
+
+
+== Input handling?
+
+*  jME3: Designed for games. Abstracting keyboard, mouse and joystick into a single, binding based interface. Low level interface available for +++<abbr title="Graphical User Interface">GUI</abbr>+++ access.
+*  jME2: Layer over keyboard, mouse and joystick. Main input interface (InputManager) can cause bloat in user code. Binding system available separately through darkfrog's input binding system.
+
+
+== GL Object handling?
+
+*  jME3:  Unused GL objects are deleted when they are garbage collected by Java.
+*  jME2:  All objects are leaked unless manually cleaned up by the user.
+
+
+== Collision/Picking?
+
+*  jME3:  BIH (Bounding interleaved hierarchy) for static mesh picking and collision. Supports Volume vs. Tri collision.
+*  jME2:  Red-black tree over entire mesh data, less efficient collision than BIH but faster generation for animated objects. Supports Tri vs. Tri collision but not Volume vs. Tri which is more commonly used.
+
+
+== Native library handling?
+
+*  jME3:  Copies natives and loads them at runtime.
+*  jME2:  None, requires user to specify java.library.path property.
+
+
+== Post processing?
+
+*  jME3:  HDR/Tonemapping, SSAO, Bloom, Radial Blur, Light Scattering, CartoonEdge.
+*  jME2:  Bloom, Basic Motion Blur
+
+
+== Shadow effects?
+
+*  jME3:  Built in the core. Customizable shadow map method, supports basic and PSSM methods.
+*  jME2:  ShadowedRenderPass for stencil shadows, issues if camera goes inside shadow volume. DirectionalShadowMapPass for basic shadow mapping.
+
+
+== Geometry handling?
+
+*  jME3:  Geometry is a scene graph element, contains a Mesh object. Meshes contain VertexBuffers which specify # of components, type, float/int buffer. This allows a single mesh to be shared along many scene graph elements. Supports features like Level of Detail and animation internally.
+*  jME2:  Geometry/TriMesh a scene graph element contains float buffers and int buffers, VBO only supports static models, custom attributes are specified manually via GLSLShaderDataLogic and do not work if VBO is used.
+
+
+== Scene graph updates?
+
+*  jME3:  Refresh flags prevent unneeded scene updates.
+*  jME2:  All data updated in updateGeometricState. Every call updates entire scene graph, locking mechanism is used to reduce unneeded updates but requires used intervention.
+
+
+== RenderState/Material
+
+*  jME3:  Only at leafs. Scriptable material system is used. materials contain techniques which contain shader &amp; render state. Shader is customized with defines specified in material instance (by user). This is a data-driven approach to materials.
+*  jME2:  Each scene graph element contains an array of RenderStates. They are combined and stored in the leafs. No data-driven solution.
+
+
+== Support for fixed-function/old gpus?
+
+*  jME3:  Supported via FixedFunc bindings in shader source.
+*  jME2:  Full support.
+
+
+== Renderer capabilities?
+
+*  jME3:  Queriable through cap system.
+*  jME2:  Queriable through the Renderer and the various renderstates.
+
+
+== Math object pooling (Vector, Matrix, etc)?
+
+*  jME3:  ThreadLocal-based system, defined as instance variables accessible by any class. Assertion-based “locking is used to prevent data corruption.
+*  jME2:  static declarations (kills multithreading in these classes) or no pooling at all.
+
+
+== Text?
+
+*  jME3:  AngelCode bitmap text
+*  jME2:  Fixed-length font, 3D text, AngelCode bitmap text
+
+
+== User interface?
+
+*  jME3:  Simple text and ortho built-in, NiftyGui integration can be used for more advanced user interface.
+*  jME2:  Only simple text and ortho. jME-desktop (not working well under MacOS X), external libs available (FengGUI, GBUI, NiftyGui).
+
+
+== Animation?
+
+*  jME3:  OgreXML-based animation system with many features. Software skinning and hardware skinning are supported.
+*  jME2:  Too many systems, creating a big mess. jME-xml and collada use one system, md2/md3 use another, milkshape models use another, ogrexml uses another and md5 uses another.
+
+
+== Spatial partitioning?
+
+*  jME3:  None.
+*  jME2:  None.
+
+
+== Model formats?
+
+*  jME3:  Ogre3D Mesh.XML and OBJ.
+*  jME2:  Static/VertexAnim: ase, obj, 3ds, md2, md3, ms3d, x3d. Skeleton: (broken) collada, ogre3d, jme-xml (md5 as a seperate lib)
+
+
+== Import/Export?
+
+*  jME3:  Same as jME2. Don't fix what's not broken.
+*  jME2:  Input/Output capsules and Savable. Binary and XML.
+
+
+== Physics?
+
+*  jME3:  Full JBullet integration.
+*  jME2:  External libs available: jME-physics, jbullet-jme, SimplePhysics.
+
+
+== Canvas support?
+
+*  jME3:  Yes.
+*  jME2:  Yes, although the +++<abbr title="Application Programming Interface">API</abbr>+++ could have been a little less convoluted.
+
+
+== Particles?
+
+*  jME3:  Yes.
+*  jME2:  Yes but +++<abbr title="Application Programming Interface">API</abbr>+++ could be a little less convoluted.
+
+
+== Terrain?
+
+*  jME3:  Image based heightmap, supports dynamic terrain loading, geomipmapping (LOD), and texture splatting. Can import Ogre3D dotScene files for non-heightmap terrain.
+*  jME2:  Image based or randomly generated heightmap. Quadtree support.

src/docs/asciidoc/documentacao.adoc

@@ -0,0 +1,119 @@
+
+
+= Documentação jMonkeyEngine
+
+Essa wiki contém guias de instalação e configuração, tutoriais de codificação jME3 e outras informaçõess que lhe ajudarão a dar andamento no seu projeto de jogo. Você pode pesquisar o conteúdo dessa wiki usando a caixa de pesquisa “Search localizado na direita-superior dessa página.
+
+
+Você também é convidado a corrigir equívicos ou problemas de digitação, como também parágrafos confusos, usando o menu “Tools localizado na direita-superior dessa página ou o botão “Edit em cada parágrafo. Você precisa estar conectado na wiki para poder editar.
+
+
+
+== Instalação
+
+*Antes de instalar, verifique a <<bsd_license#,licença>>, <<jme3/features#,funcionalidades>>, e <<jme3/requerimentos#,requerimentos>>.* Então, escolha uma das seguintes opções:
+
+[cols="4", options="header"]
+|===
+
+a| 
+<a| Recomendado     
+<a| Opcional       
+<a| Opcional  
+
+a| Você gostaria de… 
+a| Iniciar com a jMonkeyEngine 
+a| Usar a jMonkeyEngine em outra IDE 
+a| Construir uma “engine a partir do código fonte 
+
+a| Então baixe… 
+a| link:http://jmonkeyengine.org/downloads/[jMonkeyEngine SDK] 
+a| link:http://updates.jmonkeyengine.org/stable[Binários] 
+a| link:http://jmonkeyengine.googlecode.com/svn/trunk/engine[Fontes (Subversion)] 
+
+a| Você receberá… 
+a| Fontes, binários, javadoc, SDK 
+a| Ultima versão estável, fontes, javadoc. 
+a| Fontes 
+
+a| Aprenda mais… 
+a| <<sdk#,Utilizando o SDK>> +
+<<sdk/project_creation#,Criação de Projeto>> +
+
+image::sdk/jme3-jmonkeyplatform.png[jme3-jmonkeyplatform.png,with="144",height="90",align="center"]
+ 
+a| <<jme3/maven#,Configurando o JME3 com IDE compatívels com maven>> * +
+<<jme3/setting_up_netbeans_and_jme3#,Configurando o JME3 no NetBeans IDE>> * +
+<<jme3/setting_up_jme3_in_eclipse#,Configurando o JME3 no Eclipse IDE>> * +
+<<jme3/eclipse_jme3_android_jnindk#,Configurando o JME3 no Eclipse IDE (com Android e/ou JNI/NDK)>> * 
+a| <<jme3/build_from_sources#,Compilando JME3 a partir dos Fontes>> +
+<<jme3/build_jme3_sources_with_netbeans#,Compilando jME3 a partir dos Fontes com NetBeans>> +
+<<jme3/simpleapplication_from_the_commandline#,Configurando o jME3 na linha de comando>> 
+
+|===
+
+(*) O SDK cria projetos baseados em ANT que qualquer Java IDE pode importar. Nós recomendamos que usuários de outras IDEs baixem a jMonkeyEngine SDK e escolham “Arquivo→Importar Projeto→Pastas de Projeto Externo para criar um projeto sem código, apanas para gerenciar os assets. Dessa forma, você pode codificar no IDE de sua escolha e ainda utilizar o SDK para converter seus modelos para o formato .j3o.
+
+
+* EM CONSTRUÇÃO *
+
+
+
+== Crie
+
+Depois de baixado e instalado, <<jme3#,adicione esta página em seus favoritos>> e comece a escrever seu primeiro jogo!
+
+[cols="3", options="header"]
+|===
+
+a| Tutoriais 
+a| jMonkeyEngine SDK 
+a| Outras Documentações 
+
+a| <<jme3#tutorials_for_beginners,jME3 tutoriais para iniciantes>> 
+a| <<sdk#,Documentação jMonkeyEngine SDK e Vídeo Tutoriais>> 
+a| link:http://javadoc.jmonkeyengine.org/[API JavaDoc Completa] 
+
+a| <<jme3#documentation_for_intermediate_users,Artigos jME3 intermediário>> 
+a| <<sdk/comic#,jMonkeyEngine SDK - a Comédia :-)>> 
+a| <<jme3/external/blender#,Guia de Modelagem em Blender>> 
+
+a| <<jme3#documentation_for_advanced_users,jME3 documentação avançada>> 
+<a|  
+a| <<jme3/faq#,Respostas para Perguntas Frequentes>> 
+
+|===
+
+
+== Contribua
+
+Você é um desenvolvedor Java experiente que quer adicionar novas funcionalidades ou contribuír com o projeto jME3?
+
+
+*  Inspire-se com <<jme3/contributions#,contribuições>> existentes
+*  link:http://hub.jmonkeyengine.org/introduction/contributors-handbook/[Leia o guia dos Contribuídores]
+*  link:http://hub.jmonkeyengine.org/[Grite no fórum dos Contribuídores]
+*  <<jme3/jme3_source_structure#,Aprenda sobre a estrutura dos Fontes>>
+*  <<sdk#development,Escreva plugins e editores visuais para a jMonkeyEngine SDK>>
+*  <<report_bugs#,Reporte bugs e envie correções>>
+
+
+== Contato
+
+Você é bem-vindo em contribuír ou perguntar sobre o projeto: Por favor mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[contate] os
+link:http://jmonkeyengine.org/team/[desenvolvedores] ou pergunte no link:http://hub.jmonkeyengine.org/[fórum].
+
+
+*  mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[Contate o time jME]
+**  link:http://jmonkeyengine.org/team/[Core Team - Quem somos?]
+
+*  <<report_bugs#,Reporte uma falha>>
+*  link:http://hub.jmonkeyengine.org/c/documentation-jme3[Reporte documentação confusa ou faltante]
+
+
+== Línguas
+
+<<документация#,Документация на Русском>>
+<<documentacao#,Documentação em Português>>
+
+<tags><tag target="documentation" /><tag target="sdk" /><tag target="install" /></tags>

src/docs/asciidoc/documentation.adoc

@@ -0,0 +1,118 @@
+
+
+= jMonkeyEngine Documentation
+
+This documentation wiki contains installation and configuration guides, jME coding tutorials and other information that will help you get your game project going. You can search the contents of this wiki using the search box in the upper right.
+
+
+You are also very welcome to fix mistakes or spelling as well as unclear paragraphs using the “Wiki menu on top or the “Edit buttons after each paragraph. You have to be logged in to edit the wiki.
+
+
+
+== Install
+
+*Before installing, check the <<bsd_license#,license>>, <<jme3/features#,features>>, and <<jme3/requirements#,requirements>>.* Then choose one of these options:
+
+[cols="4", options="header"]
+|===
+
+a| 
+<a| Recommended     
+<a| Optional       
+<a| Optional  
+
+a| You want to… 
+a| Get started with jMonkeyEngine 
+a| Use jMonkeyEngine in another IDE 
+a| Build custom engine from sources 
+
+a| Then download… 
+a| link:http://jmonkeyengine.org/downloads/[jMonkeyEngine SDK] 
+a| link:http://updates.jmonkeyengine.org/stable[Binaries] 
+a| link:http://jmonkeyengine.googlecode.com/svn/trunk/engine[Sources (Subversion)] 
+
+a| You receive… 
+a| Sources, binaries, javadoc, SDK 
+a| Latest stable binary build, sources, javadoc. 
+a| Sources 
+
+a| Learn more here… 
+a| <<sdk#,Using the SDK>> +
+<<sdk/project_creation#,Project Creation>> +
+
+image::sdk/jme3-jmonkeyplatform.png[jme3-jmonkeyplatform.png,with="144",height="90",align="center"]
+ 
+a| <<jme3/maven#,Setting up jME3 with maven compatible IDEs>> * +
+<<jme3/setting_up_netbeans_and_jme3#,Setting up JME3 in the NetBeans IDE>> * +
+<<jme3/setting_up_jme3_in_eclipse#,Setting up JME3 in the Eclipse IDE>> * +
+<<jme3/eclipse_jme3_android_jnindk#,Setting up JME3 in the Eclipse IDE (with Android and/or JNI/NDK)>> * 
+a| <<jme3/build_from_sources#,Building JME3 from the Sources>> +
+<<jme3/build_jme3_sources_with_netbeans#,Building JME3 from the sources with NetBeans>> +
+<<jme3/simpleapplication_from_the_commandline#,Setting up JME3 on the commandline>> 
+
+|===
+
+(*) The SDK creates Ant-based projects that any Java IDE can import. We recommend users of other IDEs to also download the jMonkeyEngine SDK and choose “File→Import Project→External Project Assets to create a codeless project for managing assets only. This way you can code in the IDE of your choice, and use the SDK to convert your models to .j3o format.
+
+
+
+== Create
+
+After downloading and installing, <<jme3#,bookmark the jME Documentation page>> and start writing your first game!
+
+[cols="3", options="header"]
+|===
+
+a| Tutorials 
+a| jMonkeyEngine SDK 
+a| Other Documentation 
+
+a| <<jme3#tutorials_for_beginners,jME3 beginner tutorials>> 
+a| <<sdk#,jMonkeyEngine SDK Documentation and Video Tutorials>> 
+a| link:http://javadoc.jmonkeyengine.org/[Full API JavaDoc] 
+
+a| <<jme3#documentation_for_intermediate_users,jME3 intermediate articles>> 
+a| <<sdk/comic#,jMonkeyEngine SDK - the Comic :-)>> 
+a| <<jme3/external/blender#,Blender Modeling Guide>> 
+
+a| <<jme3#documentation_for_advanced_users,jME3 advanced documentation>> 
+<a|  
+a| <<jme3/faq#,Answers to Frequently Asked Questions>> 
+
+|===
+
+
+== Contribute
+
+Are you an experienced Java developer who wants to add new features or contribute patches to the jME3 project?
+
+
+*  Get inspired by existing <<jme3/contributions#,contributions>>
+*  link:http://hub.jmonkeyengine.org/introduction/contributors-handbook/[Read the Contributors Handbook]
+*  link:http://hub.jmonkeyengine.org/[Chime in on the Contributors Forum]
+*  <<jme3/jme3_source_structure#,Learn about the source structure>>
+*  <<sdk#development,Write jMonkeyEngine SDK plugins and visual editors>>
+*  <<report_bugs#,Report bugs and submit patches>>
+
+
+== Contact
+
+You are welcome to contribute and inquire about the project: Please mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[contact] the link:http://jmonkeyengine.org/team/[developers] or ask on the link:http://hub.jmonkeyengine.org/[forums].
+
+
+*  mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[Contact the jME team]
+**  link:http://jmonkeyengine.org/team/[Core team - Who are we?]
+
+*  <<report_bugs#,Report a bug>>
+*  link:http://hub.jmonkeyengine.org/c/documentation-jme3[Report unclear or missing documentation]
+
+
+== Languages
+
+<<документация#,Документация на Русском>> +
+
+<<documentacao#,Documentação em Português>> +
+
+<<documentation_zh#,中文版>>
+
+<tags><tag target="documentation" /><tag target="sdk" /><tag target="install" /></tags>

src/docs/asciidoc/documentation_de.adoc

@@ -0,0 +1,115 @@
+
+
+= Einführung in die jMonkeyEngine 3.0
+
+*Du bist Java Entwickler und möchtest 3D Spiele schreiben, die auf Windows, Mac, Linux, im Webbrowser, und auf der Android Plattform laufen? Dann bist du hier richtig! Das jMonkeyEngine Framework (jME) ist eine leistungsstarke, 3D Szenen-basierte Grafik +++<abbr title="Application Programming Interface">API</abbr>+++ mit <<jme3/features#,modernen Features>>.*
+
+
+Die jMonkeyEngine 3 ist ein Bündel aus JAR Dateien, das du in den Java Classpath platzierst. Die Software ist in Java geschrieben und nutzt LWJGL für den Zugriff auf OpenGL. Die jMonkeyEngine Open Source Community gibt diese Bibliotheken lizensiert unter der <<bsd_license#,BSD Lizenz>> heraus, welche sie jedem frei zur Verfügung stellt, so wie er sie benötigt – sei es für das eigene Hobby, für Lehrzwecke, oder kommerziell.
+
+
+Die dritte Version der jMonkeyEngine ist nun im Beta Stadium. Du nutzt noch die link:http://jme2.jmonkeyengine.org/[jME2]? Dann lies doch bitte unsere <<choose-jme2-or-jme3#,Begründung für die Wahl der jME2 oder jME3>> und den <<compare-jme2-jme3#,jME2/jME3 Feature-Vergleich>> und beginne mit dem Portieren zur jME3.
+
+
+
+==== Was ist das jMonkeyEngine SDK?
+
+Das link:http://jmonkeyengine.org/downloads/[jMonkeyEngine3 SDK] ist ein vorkonfiguriertes Software-Entwicklungskit, maßgeschneidert für Java Spielentwickler. Das SDK kombiniert alle jME3 Bibliotheken und einige <<sdk#,einmalige Entwickler Werkzeuge>>, die dir das Leben leichter machen, wenn du in Java programmierst und deine Projekte managst. Das SDK beinhaltet Projekt- und Dateiassistenten, einen erweiterten Code Editor, Spieldaten-Management, Dateikonverter, Szenenbetrachter und -designer, eine Codeschnipselablage, einen Terrain-Editor, und vieles mehr.
+
+
+
+== Installation
+
+*Bevor du die Installation startest, lies dir die <<bsd_license#,Lizenz>> durch, <<jme3/features#,die jME3 Features>>, und die <<jme3/requirements#,Systemanforderungen>>.* Wähle dann eine der folgenden Optionen:
+
+[cols="4", options="header"]
+|===
+
+a| 
+<a| Empfohlen     
+<a| Optional       
+<a| Optional  
+
+a| Du möchtest … 
+a| Dich mit der jMonkeyEngine vertraut machen 
+a| Die jMonkeyEngine in einer anderen IDE nutzen 
+a| Eine benutzerdefinierte Engine aus dem Quellcode erstellen 
+
+a| Dann downloade … 
+a| link:http://jmonkeyengine.org/downloads/[Das jMonkeyEngine SDK] 
+a| link:http://nightly.jmonkeyengine.org/[Binäre Dateien] 
+a| link:http://jmonkeyengine.googlecode.com/svn/trunk/engine[Denn Quellcode (Subversion)] 
+
+a| Du bekommst … 
+a| Quellcode, binäre Dateien, JavaDoc, SDK 
+a| Den aktuellsten nightly build, Quellcodes, JavaDoc. 
+a| Quellcodes 
+
+a| Erfahre mehr … 
+a| <<sdk#,Benutzung des SDK>> +
+<<sdk/project_creation#,Projekte erstellen>> +
+
+image::sdk/jme3-jmonkeyplatform.png[jme3-jmonkeyplatform.png,with="144",height="90",align="center"]
+ 
+a| <<jme3/setting_up_netbeans_and_jme3#,Nutzung der jME3 in NetBeans>> * +
+<<jme3/setting_up_jme3_in_eclipse#,Nutzung der jME3 in Eclipse>> * 
+a| <<jme3/build_from_sources#,Kompilieren der jME3 aus den Quellcodes>> +
+<<jme3/build_jme3_sources_with_netbeans#,Kompilieren der jME3 aus den Quellcodes mit NetBeans>> +
+<<jme3/simpleapplication_from_the_commandline#,Einrichtung der jME3 über die Kommandozeileneingabe>> 
+
+|===
+
+(*) Das SDK erstellt Ant-basierte Projekte, welche jede Java IDE importieren kann. Wir empfehlen Benutzern anderer IDEs sich ebenfalls das jMonkeyEngine SDK herunterzuladen und die Spieldaten dann zu importieren (File→Import Project→External Project Assets), um die Spieldaten gesondert verwalten zu können, ohne Code. So kannst du mit der IDE deiner Wahl Code schreiben, und gleichzeitig das SDK nutzen, um deine Modelle in das .j3o Format zu konvertieren.
+
+
+
+== Entwicklung des ersten, eigenen Spiels
+
+Nachdem du alles heruntergeladen und installiert hast, <<jme3#,lege dir ein Lesezeichen für die jME3 Dokumentation an>>. Dann kann es auch schon losgehen mit der Entwicklung deines ersten, eigenen Spiels! ;)
+
+[cols="3", options="header"]
+|===
+
+a| Tutorials 
+a| jMonkeyEngine SDK 
+a| Andere Dokumentationen 
+
+a| <<jme3#tutorials_for_beginners,jME3 Einsteiger Tutorial>> 
+a| <<sdk#,jMonkeyEngine SDK Dokumentation und Video Tutorials>> 
+a| link:http://jmonkeyengine.org/javadoc/[Komplettes API JavaDoc] 
+
+a| <<jme3#documentation_for_intermediate_users,jME3 Doku für geübte Benutzer>> 
+a| <<sdk/comic#,jMonkeyEngine SDK - der Comic :-)>> 
+a| <<jme3/faq#,Antworten zu häufig gestellten Fragen>> 
+
+a| <<jme3#documentation_for_advanced_users,jME3 Doku für fortgeschrittene Benutzer>> 
+a|
+a|
+
+|===
+
+
+== Wenn du etwas beitragen möchtest
+
+Du bist ein erfahrener Java Entwickler und möchtest neue Features oder Verbesserungen in das jME3 Projekt einbringen?
+
+
+*  link:http://jmonkeyengine.org/introduction/contributors-handbook/[Lies das Mitarbeiter Handbuch]
+*  link:http://www.jmonkeyengine.com/forum/index.php?board=30.0[Klinke dich im Mitarbeiter Forum ein]
+*  <<jme3/jme3_source_structure#,Lerne die Quellcode Strukturen kennen>>
+*  <<sdk#development,Schreibe Plugins für das jME SDK und visuelle Editoren>>
+*  <<report_bugs#,Melde Fehler und reiche Patches ein>>
+
+
+== Kontakt
+
+Gerne darfst du unser Projekt unterstützen, oder Fragen dazu stellen: Bitte mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[kontaktiere] die link:http://jmonkeyengine.org/team/[Entwickler] oder frage im link:http://jmonkeyengine.org/forums[Forum] nach.
+
+
+*  mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[Schreibe dem jME Team eine Mail!]
+**  link:http://jmonkeyengine.org/team/[Das Kern-Team - Wer sind wir?]
+**  link:http://jmonkeyengine.org/groups/contributor/members/[Mitarbeiter - Wer sind wir?]
+
+*  link:http://jmonkeyengine.org/wiki/doku.php/report_bugs[Du hast einen Fehler gefunden? Hier kannst du ihn melden!]
+*  link:http://code.google.com/p/jmonkeyengine/issues/list?can=2&q=label:Component-Docs[Es fehlt etwas in der Doku? Bitte gib uns bescheid!]
+<tags><tag target="documentation" /><tag target="sdk" /><tag target="install" /></tags>

src/docs/asciidoc/documentation_zh.adoc

@@ -0,0 +1,126 @@
+
+
+= jMonkeyEngine 说明文档
+
+本wiki页面包含jME3的安装和配置指南、jME3编程教程以及其他一些能够帮助你开发游戏项目的资料，请善用本页右上方的搜索框来检索整个wiki中的内容。
+
+
+本文翻译自英文版<<documentation#,jME文档>>，受编者水平所限，难免存在各种各样的问题。如果您在阅读的过程中发现任何错误，非常欢迎您直接修正错误的内容。编辑此页面需要link:http://hub.jmonkeyengine.org[官方论坛]账号，然后点击本页右上角的“Tools → Login登录。登录后点击右上角“Tools → Edit this page或者每个段落后面的“Edit按钮，即可编辑此页面。
+
+
+
+== 下载和安装
+
+*在安装之前，请查阅<<bsd_license#,许可证>>、<<jme3/features_zh#,jME3功能说明>>和<<jme3/requirements_zh#,开发需求>>，* 然后选择其中一个选项：
+
+[cols="4", options="header"]
+|===
+
+a| 
+<a| 推荐     
+<a| 可选       
+<a| 可选  
+
+a| 你打算… 
+a| 使用jMonkeyEngine SDK开发 
+a| 在其他的IDE中使用jMonkeyEngine 
+a| 利用源码来编译自定义引擎 
+
+a| 请下载… 
+a| link:http://jmonkeyengine.org/downloads/[jMonkeyEngine SDK] 
+a| link:http://updates.jmonkeyengine.org/stable[Binaries] 
+a| link:http://jmonkeyengine.googlecode.com/svn/trunk/engine[Sources (Subversion)] 
+
+a| 你会得到… 
+a| Sources, binaries, javadoc, SDK 
+a| Latest stable binary build, sources, javadoc. 
+a| Sources 
+
+a| 更多学习内容… 
+a| <<sdk_zh#,学习使用SDK>> +
+<<sdk/project_creation_zh#,使用SDK创建工程>> +
+
+image::sdk/jme3-jmonkeyplatform.png[jme3-jmonkeyplatform.png,with="144",height="90",align="center"]
+ 
+a| <<jme3/maven_zh#,在任何兼容maven的IDE中集成JME3>> * +
+<<jme3/setting_up_netbeans_and_jme3_zh#,在NetBeans中集成JME3>> * +
+<<jme3/setting_up_jme3_in_eclipse_zh#,在Eclipse中集成JME3>> * +
+<<jme3/eclipse_jme3_android_jnindk_zh#,在Eclipse(含Android及JNI/NDK)中集成JME3>> * 
+a| <<jme3/build_from_sources_zh#,编译JME3源码>> +
+<<jme3/build_jme3_sources_with_netbeans_zh#,在NetBeans中编译JME3源码>> +
+<<jme3/simpleapplication_from_the_commandline_zh#,在(Linux)命令行下开发JME3>> 
+
+|===
+
+(*) jME SDK创建的是基于Ant的项目，任何Java IDE都可以导入。我们建议其他IDE的用户也下载jME SDK，并选择 “File→Import Project→External Project Assets 来创建一个不包含任何代码的资源项目，用以管理项目中的资源文件(如模型、材质、贴图等)。这样您就可以在自己选择的IDE中编码，并利用jME SDK来将您的模型转换成.j3o格式。
+
+
+
+== 创建jME工程
+
+下载安装jME之后，请把这个<<jme3_zh#,jME教程>>加入您的书签，然后动手开发您的第一个游戏吧！
+
+[cols="3", options="header"]
+|===
+
+a| 教程 
+a| jMonkeyEngine SDK 
+a| 其他文档 
+
+a| <<jme3_zh#初级教程,jME3初级教程>> 
+a| <<sdk_zh#,jMonkeyEngine SDK 文档和视频教程>> 
+a| link:http://javadoc.jmonkeyengine.org/[Full API JavaDoc] 
+
+a| <<jme3_zh#中级教程,jME3中级教程>> 
+a| <<sdk/comic_zh#,jMonkeyEngine SDK - 漫画 :-)>> 
+a| <<jme3/external/blender_zh#,Blender建模指南>> 
+
+a| <<jme3_zh#进阶教程,jME3进阶教程>> 
+<a|  
+a| <<jme3/faq_zh#,FAQ>> 
+
+|===
+
+
+== 贡献代码
+
+想给jME3贡献新的特性和功能吗？如果你是一名熟练的Java开发者，请看下列页面：
+
+
+*  了解已有的<<jme3/contributions#,贡献>>
+*  link:http://hub.jmonkeyengine.org/introduction/contributors-handbook/[阅读贡献者手册]
+*  link:http://hub.jmonkeyengine.org/[加入官方论坛的讨论]
+*  <<jme3/jme3_source_structure_zh#,学习jME3源码架构>>
+*  <<sdk_zh#development,开发jME SDK插件以及可视化编辑器>>
+*  <<report_bugs_zh#,报告bug &amp; 提交补丁>>
+
+
+== 联系我们
+
+欢迎您的贡献和咨询：请通过mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[电子邮箱]联系link:http://jmonkeyengine.org/team/[开发团队]，或者在 link:http://hub.jmonkeyengine.org/[官方论坛]发帖提问。
+
+
+*  mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[联系jME团队]
+**  link:http://jmonkeyengine.org/team/[核心团队 - 我们是谁？]
+
+*  <<report_bugs#,发现bug>>
+*  link:http://hub.jmonkeyengine.org/c/documentation-jme3[发现文档内容含糊或文档不存在]
+
+
+== 本页的多国语言版
+
+<<documentation#,英文原版>> +
+
+<<документация#,俄语版>> +
+
+<<documentacao#,葡萄牙语>> +
+
+<<documentation_zh#,中文版>>
+
+
+
+== 中文开发者讨论群
+
+本群不是jME的官方QQ群，而是由一群国内的jME爱好者聚集的讨论群，欢迎加入讨论，群号：423979787。
+
+<tags><tag target="documentation" /><tag target="sdk" /><tag target="install" /></tags>

src/docs/asciidoc/gsoc/application.adoc

@@ -0,0 +1,68 @@
+<tags><tag target="gsoc" /></tags>
+
+
+= Application Template
+
+(Courtesy of Blender.org; link:http://wiki.blender.org/index.php/Dev:Ref/GSoC/2010/Application_Template[http://wiki.blender.org/index.php/Dev:Ref/GSoC/2010/Application_Template])
+
+
+
+== Name
+
+Please provide your full name.
+
+
+
+== Email / IRC / WWW
+
+Where can we contact you? If you frequent our +++<abbr title="Internet Relay Chat">IRC</abbr>+++ channel (#jme on irc.freenode.net) please let us know what your nick is. If you have a web page you'd like us to know about, please include it.
+
+
+
+== Synopsis
+
+A short description of your planned SoC project
+
+
+
+== Benefits to jME
+
+Describe how your project will benefit jME. Will it enhance some graphics functionality? Lower the entry barrier? Simplify a common procedure?
+
+
+
+== Deliverables
+
+Provide a user-level summary of the final output or results of your project. How does it integrate in jME, and how does it cooperate with the rest of jME's features? Note that end-user documentation should be one of the deliverables as well.
+
+
+
+== Project Details
+
+A more detailed description.
+
+
+
+== Project Schedule
+
+How long will the project take? When can you begin work?
+Include an estimated timeline of the project with mini-milestones
+Please also note any vacation time you expect to take during the project period.
+Do you have any possible school or work conflicts with your schedule?
+
+
+
+== Bio
+
+Who are you, what are you studying (and where), and what activities do you enjoy? What is your experience using jME or other computer graphics programs? What (3D) code development projects have you realized? What makes you the best person to work on this project? If you have any history contributing to jME or otherwise advocating the project, please describe your efforts.
++
+
++
+
+Send your application to mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[]
++
+
++
+
+_Thank you for applying!_
+

src/docs/asciidoc/gsoc/ideas.adoc

@@ -0,0 +1,176 @@
+<tags><tag target="gsoc" /></tags>
+
+
+= Ideas List
+
+Below is listed every idea for a prospective jME student project during GSoC.
++
+
+Got a suggestion? Please discuss it in the link:http://www.jmonkeyengine.com/forum/[forum].
++
+
+
+[quote]
+____
+ If the forum won't suffice we can always be reached at mailto:&#x63;&#x6f;&#x6e;&#x74;&#x61;&#x63;&#x74;&#x40;&#x6a;&#x6d;&#x6f;&#x6e;&#x6b;&#x65;&#x79;&#x65;&#x6e;&#x67;&#x69;&#x6e;&#x65;&#x2e;&#x63;&#x6f;&#x6d;[]
+____
+
+
+= Worth noting
+
+*Difficulty setting pending:* The developers have yet to estimate difficulty and scope for each of the suggested projects.
++
+
+*GDE-appropriate:* Many of the suggestions below would be most suitable as an extension to our WIP 'link:http://www.jmonkeyengine.com/forum/index.php?board=33.0[Game Development Environment]', but won't be identified as such until further evaluation. Doing so keeps the jME 3.0 core clean and lean.
+
+
+
+== Finish/extend sound engine
+
+jME's sound engine is almost complete, but lacks more extensive testing and has room for improvements.
+
+
+
+== New terrain system
+
+One of the most sought after features for jME is a complete terrain system, topped off with a user-friendly visual editor. → link:http://jmonkeyengine.com/wiki/doku.php/terrain_systems[Terrain Systems]
+
+
+
+== Basic AI system
+
+Basic path-finding, primitive bot behavior…
+
+
+
+== Game frameworks
+
+A great way of adding to jME3's accessibility. A 'game framework' would be a bare-bones implementation of a genre-specific, clearly defined type of gameplay, like a link:http://en.wikipedia.org/wiki/First-person_shooter[First-person_shooter].
+
+
+
+== Extended builders for particle effects
+
+
+== Cinematics
+
+A system that eases the job of handling all the different kinds of camera-, recording and playback work involved for making a cinematic in any type of game.  Additionally, the use of pre-rendered and edited footage in-game (either in 3D space or contained in cut scenes)
+
+
+
+== Game Development Environment: Editors
+
+Editors for the gde could become a way to avoid bloating the core engine. More specialized tools like cinematics creation and terrain editing might be best suited as an extension to the jME3 Game Development Environment.
+
+
+
+== Post process effect
+
+Add a new post process effect to jME, follow the way the HDRProcessor and BasicShadowProcessor were designed. Some examples of post process effects:
+
+
+*  Motion Blur
+*  Depth of Field
+*  Parallel-Split Shadow Maps
+*  More advanced shadow filtering (VSM, Jittered)
+*  Bloom
+
+
+== jME Importer
+
+Create a new importer for jME, it should be a popular format for most effectiveness. Some examples:
+
+
+*  3DS
+*  OBJ - MTL (material) file import. Should be able to support normal and specular maps!
+*  Collada (advanced)
+
+
+== Scene editor
+
+Create a scene editor, with model importing, moving around models, editing particles and applying materials, etc.
+If you want something simpler than the above, you can just write a particle editor
+
+
+
+== Game state system: AppState
+
+Create a game state system, similar to jME2's StandardGame and GameState. Please call it AppState though.
+
+
+
+== Improved multithreading support
+
+(advanced)
+
+
+
+== Deferred rendering
+
+(advanced)
+
+
+
+== Hardware skinning
+
+
+== A jME Game
+
+Create a game using jME. Doesn't have to be advanced or graphically intense, something like pacman in 3D for example for geeneral optimization of the engine and many community resources.
+
+
+
+== Android Interface
+
+E.g. Create “virtual arrow keys and other buttons on the screen, for those phones without keyboard but only touchscreen.
+
+
+
+== Android Multitouch support
+
+(Android 2.1 only?)
+
+
+
+== Android Trackball support
+
+
+== General core Android optimizations
+
+
+== Evaluation: Game Asset Pipeline
+
+*  Evaluate various model converters and creators, audio tools, 3-D and 2-D graphic tools (free and paid).
+*  Write an example make script that regenerates the artwork everytime the designer made changes, and copies the files to the developer's directory.
+*  Collect the best practices (pros/cons/limitations of tools and approaches) in a comparison table.  
+
+
+== Evaluation: Deployment Options
+
+*  Applet, Webstart, OneJAR, …
+*  Free vs commercial executable creators for all supported operating systems…
+*  Icons, auto-updaters, and installers, for all supported operating systems…
+*  Write an ant target that generates:
+**  zipped release-ready desktop executables for all operating systems…
+**  Webstartable or Applet-ready JARs…
+
+*  Collect the best practices (pros/cons/limitations) in a comparison table.
+
+
+== jME on the iPhone
+
+XMLVM is a project that let's you convert .class-files (and .net-clr files) into xml-files. This xml-files then 
+can be translated into different targets and also objective c. They already implemented an compatibilty layer you can write your android-application against and create iphone objective c-sourcecode including makefiles out of it. (It seems  that) all you have to do is to run the makefile on a MAC. Kev Glass implemented the opengl-translation and one nehe-lesson is included as example. 
+
+
+Here some links:
+
+
+link:http://www.xmlvm.org/overview/[http://www.xmlvm.org/overview/]
+link:http://www.xmlvm.org/iphone/[http://www.xmlvm.org/iphone/]
+link:http://www.cokeandcode.com/aboidblog[http://www.cokeandcode.com/aboidblog]
+
+
+opengl-compatlib (in sourcefolder src/xmlvm2objc/compat-lib/java ):
+org..xmlvm.iphone.gl
+

src/docs/asciidoc/gsoc/students_handbook.adoc

@@ -0,0 +1,9 @@
+<tags><tag target="gsoc" /></tags>
+
+
+= GSoC Student's Handbook
+
+This page is an extension of the link:http://www.jmonkeyengine.com/wiki/doku.php/contributors_handbook[contributor's handbook].
+
+
+*  link:http://www.ogre3d.org/wiki/index.php/GSoC_Development_Advices[http://www.ogre3d.org/wiki/index.php/GSoC_Development_Advices]

src/docs/asciidoc/jm3/solutions.adoc

@@ -0,0 +1,449 @@
+
+
+= Some proposed solutions
+
+This is a user-proposed group of solutions for some or all of the exercises presented throughout the beginner tutorials (link:http://jmonkeyengine.org/wiki/doku.php/jme3#tutorials_for_beginners[http://jmonkeyengine.org/wiki/doku.php/jme3#tutorials_for_beginners]). 
+There are several ways to do them, so take what you see with a grain of salt, and actually try to do them yourself instead of jumping to the solution, for it is the best way to learn!
+
+
+
+== Hello Update Loop
+
+
+=== Exercise 1
+
+It will spin the other way around.
+
+
+
+=== Exercise 2
+
+First, one must declare another Geometry, for example, a red cube:
+
+
+[source,java]
+----
+protected Geometry redCube;
+
+public void simpleInitApp() {
+    ...
+    
+    // Creates the new cube
+    Box b2 = new Box(Vector3f.ZERO, 1, 1, 1);
+    redCube = new Geometry("red cube", b2);
+    
+    // For the new cube to become red colored
+    Material mat2 = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+    mat2.setColor("Color", ColorRGBA.Red);
+    redCube.setMaterial(mat2);
+    
+    // To position the red cube next the other cube
+    redCube.move(2, 0, 0);
+    
+    // Makes the red cube appear on screen
+    rootNode.attachChild(redCube);
+}
+----
+To have the red cube spin twice as fast as the other cube, simply make it rotate on the same axis but with double the value:
+
+
+[source,java]
+----
+public void simpleUpdate(float tpf) {
+    // make the player rotate
+    player.rotate(0, 2*tpf, 0);
+    
+    // make the red cube rotate twice as fast the player
+    redCube.rotate(0, 4*tpf, 0);
+}
+----
+
+=== Exercise 3
+
+One possible solution is to shrink or grow depending on current size. The cube may start by either growing or shrinking. If the cube is growing, it will start shrinking instead only when it reaches a size large enough. If the cube is shrinking, it will start growing again, only when the size is small enough. In short, the cube should switch between growing and shrinking when it reaches a specified maximum and minimum sizes. The following code is an example of this solution:
+
+
+[source,java]
+----
+private boolean grow = true;
+...
+public void simpleUpdate(float tpf) {
+        if (grow) {
+                player.scale(1 + (3f * tpf));
+        } else {
+                player.scale(1 - (3f * tpf));
+        }
+
+        Vector3f s = player.getLocalScale();
+        if (s.getX() > 1.2f) {
+                grow = false;
+        } else if (s.getX() < 0.8f) {
+                grow = true;
+        }
+}
+----
+The cube starts by growing, and when it reaches a size larger than 120% its original size, it starts shrinking instead. The cube will then keep shrinking, until it reaches a size smaller than 80% its original size, which will make it start growing again, and so on.
+
+
+Another approach is to switch between shrinking and growing every chosen unit of time. The tpf variable stores the time per frame rendered, so if you sum every tpf at the simpleUpdate method, you get the time passed since the game started. Using time like a stopwatch, one may grow the cube for some time, and then shrink the cube for the same amount of time, and start over again. The following code shows an example of this solution:
+
+
+[source,java]
+----
+// Time passed
+private float timeVar = 0;
+...
+public void simpleUpdate(float tpf) {
+    timeVar += tpf;
+    if (timeVar < 2) {
+        player.scale(1 + tpf * 0.4f);
+    } else if (timeVar < 4) {
+        player.scale(1 - tpf * 0.4f);
+    } else {
+        timeVar = 0;
+    }
+}
+----
+The cube grows for 2 two seconds, then shrinks for another 2 seconds, and repeats indefinitely.
+
+
+Another approach is to set the cube scale as the result of a sine wave. This results in a smooth repetitive oscillating scale. Note however that this approach is computational expensive due to the use of the sine function. One may create a sine wave by calculating sine as a function of time. As such, for each iteration of the simpleUpdate method, the scale is set as the result of sine as function of time plus the original cube scale. The following code shows an example of this approach:
+
+
+[source,java]
+----
+public void simpleUpdate(float tpf) {
+    float timeInSec = timer.getTimeInSeconds();
+    float initScale = 1;
+    float amplitude = 0.5f;
+    float angularFrequency = 1;
+    float scale = initScale + amplitude * FastMath.sin(timeInSec * angularFrequency);
+    player.setLocalScale(scale);
+}
+----
+The cube should repeatedly and smoothly grow and shrink and have maximum and minimum scale of 0.5 and 1.5 its original size. The following variables can change the scale behavior:
+
+
+*  initScale - Sets the initial scale of cube
+*  amplitude - Increases minimum and maximum scale
+*  angularFrequency - Increases scale speed
+
+
+=== Exercise 4
+
+Same logic! Use a timeVar, and make the Material declaration + initialization line we had @ simpleInitApp() into only the initialization, with the Material mat; going as a global variable, so we can access it on the simpleUpdate()! Like so:
+
+
+[source,java]
+----
+protected Material mat;
+----
+As global var, then the initialization cuts off the Material bit:
+
+
+[source,java]
+----
+mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+----
+And then the simpleUpdate()
+
+
+[source,java]
+----
+public void simpleUpdate(float tpf) {
+    timeVar += tpf;
+    if (timeVar > 1) {
+        mat.setColor("Color", ColorRGBA.randomColor());
+        timeVar= 0;
+    }
+}
+----
+
+=== Exercise 5
+
+A possible solution is to change the rotation axis of player from y to x, and make it move along the z axis:
+
+
+[source,java]
+----
+public void simpleUpdate(float tpf) {
+    // make the player rotate
+    player.rotate(2*tpf, 0, 0);
+    player.move(0, 0, 2*tpf);
+}
+----
+The above code should make the player roll towards the camera.
+
+
+
+== Hello Input
+
+
+=== Exercise 1
+
+First, add the mappings for the Up and Down actions to the initKeys() method:
+
+
+[source,java]
+----
+private void initKeys() {
+    ...
+    inputManager.addMapping("Up", new KeyTrigger(KeyInput.KEY_H));
+    inputManager.addMapping("Down", new KeyTrigger(KeyInput.KEY_L));
+    ...
+    inputManager.addListener(combinedListener, new String[]{"Left", "Right", "Up", "Down", "Rotate"});
+}
+----
+Then implement the actions in the onAnalog() method:
+
+
+[source,java]
+----
+public void onAnalog(String name, float value, float tpf) {
+    if (isRunning) {
+        ...
+        if (name.equals("Up")) {
+            Vector3f v = player.getLocalTranslation();
+            player.setLocalTranslation(v.x, v.y + value * speed, v.z);
+        }
+        if (name.equals("Down")) {
+            Vector3f v = player.getLocalTranslation();
+            player.setLocalTranslation(v.x, v.y - value * speed, v.z);
+        }
+    } else {
+        ...
+    }
+}
+----
+This should enable cube to move upwards, if the H key is pressed, and downwards, if the L key is pressed.
+
+
+
+=== Exercise 2
+
+Following the proposed solution 1, add new mappings for the mouse wheel in the initKeys() method:
+
+
+[source,java]
+----
+private void initKeys() {
+    ...
+    inputManager.addMapping("Up", new KeyTrigger(KeyInput.KEY_H),
+                                  new MouseAxisTrigger(MouseInput.AXIS_WHEEL, true));
+    inputManager.addMapping("Down", new KeyTrigger(KeyInput.KEY_L),
+                                    new MouseAxisTrigger(MouseInput.AXIS_WHEEL, false));
+    ...
+}
+----
+Now you should be able to scroll the cube up or down with the mouse wheel.
+
+
+
+=== Exercise 3
+
+When the controls are user-chosen.
+
+
+
+== Hello Picking
+
+
+=== Exercise 1
+
+You can jump right off and obtain the hit object's material, by acessing the “closest object we previously acquired, obtain it's geometry through .getGeometry(), and then get the Geometry's material through .getMaterial(), like so: 
+
+
+[source,java]
+----
+Material g = closest.getGeometry().getMaterial();
+----
+It's the same as going through the two steps hinted in the tips: `Geometry g = closest.getGeometry(); Material material = g.getMaterial();`
+Finally, you need only add this line: `material.setColor(“Color, ColorRGBA.randomColor())` , which will change the material from the hit object to a random color!
+
+
+The lines can be added anywhere within the `if (results.size() &gt; 0)` block, after declaring the closest object. End result is as so:
+
+
+[source,java]
+----
+Material material = closest.getGeometry().getMaterial();
+material.setColor("Color", ColorRGBA.randomColor());
+----
+
+=== Exercise 2
+
+First of all, we need some light shed to make the model visible! Add a simple DirectionalLight like previously showed.
+Then, declare a `Spatial golem` variable outside of methods. Then initialize golem to load his model: 
+
+
+[source,java]
+----
+golem = assetManager.loadModel("Models/Oto/Oto.mesh.xml");
+----
+Now we need him to show up! So we need to attach him: but the rootNode won't do, because we're checking collision with it's child, the shootables node! So we attach it to shootables!
+
+
+[source,java]
+----
+shootables.attachChild(golem);
+----
+
+=== Exercise 3
+
+Here is my code, it works and it is well commented.
+
+
+[source,java]
+----
+package jme3test.helloworld;
+
+import com.jme3.app.SimpleApplication;
+import com.jme3.collision.CollisionResult;
+import com.jme3.collision.CollisionResults;
+import com.jme3.font.BitmapText;
+import com.jme3.input.KeyInput;
+import com.jme3.input.MouseInput;
+import com.jme3.input.controls.ActionListener;
+import com.jme3.input.controls.KeyTrigger;
+import com.jme3.input.controls.MouseButtonTrigger;
+import com.jme3.light.DirectionalLight;
+import com.jme3.material.MatParam;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.Ray;
+import com.jme3.math.Vector3f;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.Spatial;
+import com.jme3.scene.shape.Box;
+import com.jme3.scene.shape.Sphere;
+import com.jme3.system.SystemListener;
+
+public class HelloPicking extends SimpleApplication
+{
+
+    public static void main(String[] args)
+    {
+	HelloPicking app = new HelloPicking();
+	app.start();
+    }
+    private Node shootables;
+    private Node inventory;
+    private Vector3f oldPosition;
+
+    @Override
+    public void simpleInitApp()
+    {
+	initCrossHairs();
+	initKeys();
+	shootables = new Node("Shootables");
+	inventory = new Node("Inventory");
+	guiNode.attachChild(inventory);
+	// add a light to the HUD so we can see the robot
+	DirectionalLight sun = new DirectionalLight();
+	sun.setDirection(new Vector3f(0, 0, -1.0f));
+	guiNode.addLight(sun);
+	rootNode.attachChild(shootables);
+	shootables.attachChild(makeCube("a Dragon", -2f, 0f, 1f));
+	shootables.attachChild(makeCube("a tin can", 1f, -2f, 0f));
+	shootables.attachChild(makeCube("the Sheriff", 0f, 1f, -2f));
+	shootables.attachChild(makeCube("the Deputy", 1f, 0f, -4f));
+	shootables.attachChild(makeFloor());
+	shootables.attachChild(makeCharacter());
+    }
+    private ActionListener actionListener = new ActionListener()
+    {
+	public void onAction(String name, boolean keyPressed, float tpf)
+	{
+	    if (name.equals("Shoot") && !keyPressed)
+	    {
+		if (!inventory.getChildren().isEmpty())
+		{
+		    Spatial s1 = inventory.getChild(0);
+		    // scale back
+		    s1.scale(.02f);
+		    s1.setLocalTranslation(oldPosition);
+		    inventory.detachAllChildren();
+		    shootables.attachChild(s1);
+		}
+		else
+		{
+		    CollisionResults results = new CollisionResults();
+		    Ray ray = new Ray(cam.getLocation(), cam.getDirection());
+		    shootables.collideWith(ray, results);
+
+		    if (results.size() > 0)
+		    {
+			CollisionResult closest = results.getClosestCollision();
+			Spatial s = closest.getGeometry();
+			// we cheat Model differently with simple Geometry
+			// s.parent is Oto-ogremesh when s is Oto_geom-1 and that is what we need
+			if (s.getName().equals("Oto-geom-1"))
+			{
+			    s = s.getParent();
+			}
+			// It's important to get a clone or otherwise it will behave weird
+			oldPosition = s.getLocalTranslation().clone();
+			shootables.detachChild(s);
+			inventory.attachChild(s);
+			// make it bigger to see on the HUD
+			s.scale(50f);
+			// make it on the HUD center
+			s.setLocalTranslation(settings.getWidth() / 2, settings.getHeight() / 2, 0);
+		    }
+		}
+	    }
+	}
+    };
+
+    private void initKeys()
+    {
+	inputManager.addMapping("Shoot",
+				new KeyTrigger(KeyInput.KEY_SPACE),
+				new MouseButtonTrigger(MouseInput.BUTTON_LEFT));
+	inputManager.addListener(actionListener, "Shoot");
+    }
+    protected Geometry makeCube(String name, float x, float y, float z)
+    {
+	Box box = new Box(1, 1, 1);
+	Geometry cube = new Geometry(name, box);
+	cube.setLocalTranslation(x, y, z);
+	Material mat1 = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+	mat1.setColor("Color", ColorRGBA.randomColor());
+	cube.setMaterial(mat1);
+	return cube;
+    }
+    protected Geometry makeFloor()
+    {
+	Box box = new Box(15, .2f, 15);
+	Geometry floor = new Geometry("the Floor", box);
+	floor.setLocalTranslation(0, -4, -5);
+	Material mat1 = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+	mat1.setColor("Color", ColorRGBA.Gray);
+	floor.setMaterial(mat1);
+	return floor;
+    }
+    protected void initCrossHairs()
+    {
+	setDisplayStatView(false);
+	guiFont = assetManager.loadFont("Interface/Fonts/Default.fnt");
+	BitmapText ch = new BitmapText(guiFont, false);
+	ch.setSize(guiFont.getCharSet().getRenderedSize() * 2);
+	ch.setText("+");
+	ch.setLocalTranslation(
+		settings.getWidth() / 2 - ch.getLineWidth() / 2, settings.getHeight() / 2 + ch.getLineHeight() / 2, 0);
+	guiNode.attachChild(ch);
+    }
+    protected Spatial makeCharacter()
+    {
+	Spatial golem = assetManager.loadModel("Models/Oto/Oto.mesh.xml");
+	golem.scale(0.5f);
+	golem.setLocalTranslation(-1.0f, -1.5f, -0.6f);
+	System.out.println("golem.locaoTranslation:" + golem.getLocalTranslation());
+	DirectionalLight sun = new DirectionalLight();
+	sun.setDirection(new Vector3f(0, 0, -1.0f));
+	golem.addLight(sun);
+	return golem;
+    }
+}
+----

src/docs/asciidoc/jme3.adoc

@@ -0,0 +1,366 @@
+
+
+= jMonkeyEngine Tutorials and Documentation
+
+
+== Tutorials for Beginners
+
+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]
+
+
+
+image::jme3/beginner/beginner-physics.png[beginner-physics.png,with="360",height="291",align="right"]
+
+
+
+*  Make sure you are familiar with basic <<jme3/terminology#,3D game development concepts>> such as <<jme3/the_scene_graph#,the scene graph>>.
+
+..  <<jme3/beginner/hello_simpleapplication#,Hello SimpleApplication>> – Initializing a SimpleApplication
+..  <<jme3/beginner/hello_node#,Hello Node>> – Transforming Geometries and Nodes in the Scenegraph
+..  <<jme3/beginner/hello_asset#,Hello Assets>> – Loading 3-D models, scenes, and other assets.
+..  <<jme3/beginner/hello_main_event_loop#,Hello Loop>> – Triggering actions in the update loop
+..  <<jme3/beginner/hello_input_system#,Hello Input>> – Responding to keyboard and mouse input
+..  <<jme3/beginner/hello_material#,Hello Material>> – Setting Materials, Textures, Transparency
+..  <<jme3/beginner/hello_animation#,Hello Animation>> – Controlling animated models
+..  <<jme3/beginner/hello_picking#,Hello Picking>> – Shooting, pressing buttons, selecting, picking up items
+..  <<jme3/beginner/hello_collision#,Hello Collision>> – Making walls and floors solid
+..  <<jme3/beginner/hello_terrain#,Hello Terrain>> – Creating hilly landscapes with textures
+..  <<jme3/beginner/hello_audio#,Hello Audio>> – Accompanying places and actions with 3D sound
+..  <<jme3/beginner/hello_effects#,Hello Effects>> – Creating particle effects such as fire, explosions, spells.
+..  <<jme3/beginner/hello_physics#,Hello Physics>> – Bouncing ball and falling bricks
+..  <<jme3/beginner/hellovector#,Hello Vector3f>> – Vector visualization &amp; vector operations
+..  <<jme3/beginner/hellochasecam#,Hello Chase camera>> – Chase camera (aka 3rd person camera) example
+
+See also: <<sdk/sample_code#,Trouble running the samples>>?
+
+
+For more help getting started, check out this tuts+ guide on “link:http://gamedevelopment.tutsplus.com/articles/how-to-learn-jmonkeyengine-3--gamedev-10479[ How to learn jMonkeyEngine 3].
+
+
+
+== Documentation for Intermediate Users
+
+Now that you understood the basics, let's put it all together. The following intermediate articles help you to understand how to use these concepts in context.
+
+
+*jMonkeyEngine3 Concepts*
+
+
+*  <<jme3/intermediate/best_practices#,Best Practices>>
+*  <<jme3/intermediate/simpleapplication#,SimpleApplication>>
+*  <<jme3/intermediate/appsettings#,AppSettings>>
+*  <<jme3/intermediate/file_types#,File Types>>
+*  <<jme3/intermediate/optimization#,Optimization>>
+*  <<jme3/faq#,Frequently Asked Questions (FAQ)>>
+
+*Maths Concepts*
+
+
+*  <<jme3/math_for_dummies#,jME3 Math for Dummies>>
+*  <<jme3/intermediate/math#,Short 3D math &quot;cheat sheet&quot;>>
+*  <<jme3/math#,jME3 math overview>>
+*  <<jme3/math_video_tutorials#,Videos: jME3 math video tutorial series>>
+
+*3D Graphics Concepts*
+
+
+*  <<jme3/intermediate/multi-media_asset_pipeline#,Multi-Media Asset Pipeline>>
+*  <<jme3/scenegraph_for_dummies#,3D Scene Graph for Dummies>>
+*  <<jme3/terminology#,3D Graphics Terminology>>
+*  <<jme3/intermediate/how_to_use_materials#,How to Use Materials>>
+*  <<jme3/intermediate/transparency_sorting#,Transparency Sorting>>
+*  <<jme3/external/blender#,Creating compatible models in blender>>
+*  <<jme3/external/3dsmax#,Creating compatible models in 3dsmax>>
+
+*Game Tutorials*
+
+
+*  link:http://gamedevelopment.tutsplus.com/series/cross-platform-vector-shooter-jmonkeyengine--gamedev-13757[Neon Vector Shooter tutorial on Tuts+]
+
+*Video Use Case Tutorials*
+- Note these videos use alpha features only available in the next release
+
+
+*  link:http://www.youtube.com/watch?v=-OzRZscLlHY[Video: jMonkeyEngine SDK Use Case Demo 1 (Quixote)]
+*  link:http://www.youtube.com/watch?v=6-YWxD3JByE[Video: jMonkeyEngine SDK Use Case Demo 2 (Models and Materials)]
+
+Learn from sample code in link:https://github.com/jMonkeyEngine/jmonkeyengine/tree/master/jme3-examples/src/main/java/jme3test[src/main/java/jme3test] (also available in the sdk by File &gt; New Project &gt; JME3 Tests) and the example games provided by the community!
+
+
+
+== Documentation for Advanced Users
+
+Now that you understand the concepts, it's time to make the most of the jMonkeyEngine. Deep-dive into the +++<abbr title="Application Programming Interface">API</abbr>+++ and learn about all options, including less commonly used advanced methods. Don't over-extend yourself, developing a good game requires time and dedication. One step at a time, champ! :)
+
+
+*Controlling Game Logic*
+
+
+*  <<jme3/advanced/update_loop#,Update Loop>>
+*  <<jme3/advanced/application_states#,Application States>>
+*  <<jme3/advanced/custom_controls#,Custom Controls>>
+**  link:http://www.youtube.com/watch?v=MNDiZ9YHIpM[Video: How to control any scene node]
+**  link:http://www.youtube.com/watch?v=-OzRZscLlHY[Video: How to remote control a character in a scene]
+
+*  <<jme3/advanced/multithreading#,Multithreading>>
+
+*Managing Objects in the 3D Scene Graph*
+
+
+*  <<jme3/advanced/traverse_scenegraph#,Traverse SceneGraph>>
+*  <<jme3/advanced/spatial#,Spatial: Node versus Geometry>>
+*  <<jme3/advanced/mesh#,Mesh>>
+**  <<jme3/advanced/shape#,Shape>>
+**  <<jme3/advanced/3d_models#,3D Models>>
+**  <<jme3/advanced/custom_meshes#,Custom Meshes>>
+
+*  <<jme3/advanced/asset_manager#,Asset Manager>>
+*  <<jme3/advanced/save_and_load#,Saving and Loading Nodes (.J3O Files)>>
+*  <<jme3/advanced/collision_and_intersection#,Collision and Intersection>>
+*  <<jme3/advanced/level_of_detail#,Level of Detail>>
+
+*Animations and Scenes*
+
+
+*  <<jme3/advanced/animation#,Animation>>
+*  <<jme3/advanced/cinematics#,Cinematics (cutscenes, fake destruction physics)>>
+*  <<jme3/advanced/motionpath#,MotionPaths and waypoints>>
+*  <<jme3/external/blender#,Creating jME3 compatible 3D models in Blender>>
+*  <<jme3/advanced/makehuman_blender_ogrexml_toolchain#,MakeHuman Blender OgreXML toolchain for creating and importing animated human characters>>
+*  <<sdk/blender#,Converting Blender Models to JME3 (.J3o files)>>
+**  link:https://www.youtube.com/watch?v=QiLCs4AKh28[Video: Import animated models from Blender 2.6 to JME3]
+**  link:http://www.youtube.com/watch?v=NdjC9sCRV0s[Video: Creating and Exporting OgreXML Animations from Blender 2.61 to JME3]
+**  link:https://docs.google.com/fileview?id=0B9hhZie2D-fENDBlZDU5MzgtNzlkYi00YmQzLTliNTQtNzZhYTJhYjEzNWNk&hl=en[Scene Workflow:]
+
+
+Create jme3 compatible racing tracks in blender
+* link:http://www.youtube.com/watch?v=3481ueuDJwQ&feature=youtu.be[Video: Create jme3 compatible models in blender]
+
+
+Exporting OgreXML scenes from Blender to JME3
+
+
+*  link:https://docs.google.com/leaf?id=0B9hhZie2D-fEYmRkMTYwN2YtMzQ0My00NTM4LThhOTYtZTk1MTRlYTNjYTc3&hl=en[Animation Workflow: Create Animated UV-Mapped OgreXML Models in Blender, and use them in JME3]
+**  link:http://www.youtube.com/watch?v=IDHMWsu_PqA[Video: Creating Worlds with Instances in Blender]
+**  <<jme3/advanced/ogrecompatibility#,OgreCompatibility>>
+
+*Materials, Light, Shadow*
+
+
+*  <<jme3/intermediate/how_to_use_materials#,How to Use Materials>>
+*  <<jme3/advanced/j3m_material_files#,Creating .j3m Materials>>
+*  <<jme3/advanced/material_definitions#,How to Use Material Definitions (.j3md)>>
+*  <<jme3/advanced/materials_overview#,All Material Definition Properties>>
+*  <<jme3/advanced/anisotropic_filtering#,Anisotropic Filtering for Textures>>
+*  <<jme3/advanced/light_and_shadow#,Light and Shadow>>
+*  <<jme3/advanced/jme3_shaders#,About JME3 and Shaders>>
+*  <<jme3/advanced/jme3_shadernodes#,Shader Node System>>
+*  <<jme3/advanced/jme3_srgbpipeline#,Gamma correction or sRGB pipeline>>
+*  <<jme3/shader_video_tutorials#,Videos: jME3 introduction to shaders video tutorial series>>
+*  link:http://www.youtube.com/watch?v=IuEMUFwdheE[Video: jME3 Material with Alpha Channel]
+
+*Physics Integration*
+
+
+*  <<jme3/advanced/physics#,Physics: Gravity, Collisions, Forces>>
+*  <<jme3/advanced/bullet_multithreading#,Multi-Threaded Physics>>
+*  <<jme3/advanced/physics_listeners#,Physics Listeners and Collision Detection>>
+*  <<jme3/advanced/hinges_and_joints#,Hinges and Joints>>
+*  <<jme3/advanced/walking_character#,Walking Character>>
+*  <<jme3/advanced/ragdoll#,Ragdoll>>
+*  <<jme3/advanced/vehicles#,Vehicles>>
+*  <<jme3/advanced/ray_and_sweep_tests#,Physics Rays and Sweep Tests>>
+*  link:http://www.youtube.com/watch?v=yS9a9o4WzL8[Video: Mesh Tool &amp; Physics Editor]
+
+*Audio and Video*
+
+
+*  <<jme3/advanced/audio#,Audio: Playing Sounds>>
+*  <<jme3/advanced/audio_environment_presets#,Audio Environment Presets>>
+*  <<jme3/advanced/video#,Video: Playing Clips>>
+*  <<jme3/advanced/screenshots#,Capture Screenshots>>
+*  <<jme3/advanced/capture_audio_video_to_a_file#,Capture Audio/Video to a File>>
+
+*Post-Processor Filters and Effects*
+
+
+*  <<jme3/advanced/effects_overview#,Effects and Filters Overview>>
+*  <<jme3/advanced/bloom_and_glow#,Bloom and Glow>>
+*  <<jme3/advanced/particle_emitters#,Particle Emitters>>
+
+*Landscapes*
+
+
+*  <<jme3/advanced/sky#,Sky>>
+*  <<jme3/advanced/terrain#,Terrain (TerraMonkey)>>
+*  <<jme3/advanced/endless_terraingrid#,Endless Terrain (TerrainGrid)>>
+*  <<jme3/advanced/terrain_collision#,Terrain Collision>>
+*  <<jme3/contributions/cubes#,Cubes - A Block World Framework>>
+*  <<jme3/advanced/water#,Simple Water>>
+*  <<jme3/advanced/post-processor_water#,Post-Processor Water (SeaMonkey)>>
+*  <<jme3/contributions/vegetationsystem#,Vegetation System>>
+
+*Artificial Intelligence (AI)*
+
+
+*  <<jme3/advanced/recast#,Recast Navigation>>
+*  <<jme3/advanced/building_recast#,Updating and building Recast Native Bindings>>
+*  <<jme3/advanced/monkey_brains#,Monkey Brains>>
+*  <<jme3/advanced/steer_behaviours#,Steer Behaviours>>
+
+*Multiplayer Networking*
+
+
+*  <<jme3/advanced/networking#,Multiplayer Networking (SpiderMonkey)>>
+*  <<jme3/advanced/headless_server#,Headless Server>>
+*  <<jme3/advanced/monkey_zone#,Monkey Zone: Multi-Player Demo Code>>
+*  <<jme3/advanced/open_game_finder#,Open Game Finder>>
+*  <<jme3/advanced/networking_video_tutorials#,Videos: jME3 networking video tutorial series>> 
+
+*Entity Systems*
+
+
+*  <<jme3/contributions/entitysystem#, The Zay-ES Entity System>>
+
+*Camera*
+
+
+*  <<jme3/advanced/camera#,Camera>>
+*  <<jme3/advanced/making_the_camera_follow_a_character#,Making the Camera Follow a Character>>
+*  <<jme3/advanced/remote-controlling_the_camera#,Remote-Controlling the Camera>>
+*  <<jme3/advanced/multiple_camera_views#,Multiple Camera Views>> 
+
+*User Interaction*
+
+
+*  <<jme3/advanced/input_handling#,Input Handling>>
+**  link:https://github.com/jMonkeyEngine-Contributions/Lemur/wiki/Modules[Lemur Scene Graph Tools]
+***  link:http://hub.jmonkeyengine.org/t/lemur-gems-1-inputmapper-based-camera-movement/28703[Lemur Gems #1 - Input mapper based camera movement. ]
+***  link:http://hub.jmonkeyengine.org/t/lemur-gems-2-inputmapper-delegates/28710[Lemur Gems #2 - Input mapper delegates]
+***  link:http://hub.jmonkeyengine.org/t/lemur-gems-3-scene-picking/28713[Lemur Gems #3 - Scene picking]
+
+
+*  <<jme3/advanced/combo_moves#,Combo Moves>>
+*  <<jme3/advanced/mouse_picking#,Mouse Picking: Click to Select>>
+
+*Graphical User Interface*
+
+
+*  link:https://github.com/jMonkeyEngine-Contributions/Lemur[Lemur - a native jME3 GUI library with scene graph tools]
+*  <<jme3/contributions/tonegodgui#,tonegodGUI - a native jME3 GUI library>>
+*  <<jme3/advanced/nifty_gui#,Nifty GUI - JME3 Integration Tutorial>>
+*  <<jme3/advanced/nifty_gui_best_practices#,Nifty GUI - Best Practices>>
+*  <<jme3/advanced/nifty_gui_scenarios#,Nifty GUI Scenarios (Load Screen etc)>>
+*  <<jme3/advanced/hud#,Head-Up Display (HUD)>>
+*  <<jme3/advanced/localization#,Localization>>
+*  <<jme3/advanced/swing_canvas#,Swing Canvas>>
+
+*Custom Rendering*
+
+
+*  <<jme3/advanced/jme3_forwardrendering#,Forward Rendering process>>
+*  <<jme3/advanced/jme3_renderbuckets#,Render Buckets>>
+
+*Custom Tools*
+
+
+*  <<jme3/tools/navigation#,Mercator Projection Tool (Marine Navigation)>>
+*  <<jme3/tools/charts#,Visualizing Maps in JME3 (Marine Charts)>>
+*  <<jme3/advanced/atom_framework#,Atom framework. Mash-up of other plugins>>
+
+*Logging and Debugging*
+
+
+*  <<jme3/advanced/logging#,Logging>>
+*  <<sdk/log_files#,Log Files>>
+*  <<jme3/advanced/read_graphic_card_capabilites#,Read Graphic Card Capabilites>>
+*  <<jme3/advanced/debugging#,Debugging with Wireframes>>
+
+*Android specific development*
+
+
+*  <<jme3/advanced/android#,Android Project Cheat Sheet>>
+
+*Deployment*
+
+
+*  <<jme3/android#,Android>>
+*  <<sdk/application_deployment#,Application Deployment (using jMonkeyEngine SDK)>>
+*  <<jme3/webstart#,WebStart Deployment (without jMonkeyEngine SDK)>>
+
+*Scripting*
+
+
+*  <<jme3/scripting#, Groovy scripting>>
+
+*Virtual Reality &amp; Simulation*
+
+
+*  <<jme3/virtualreality#, Virtual Reality. OpenCV &amp; JavaCV>>
+
+*jMonkey User Contributions*
+
+
+*  <<jme3/contributions#, Contributions - User made utilities to add functionality to the engine.>>
+
+*Sample Projects*
+
+
+*  <<sdk/sample_code#,JmeTests>> – The “official sample project JmeTests.
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/BookSamples/#BookSamples%2Fsrc[BookSamples] – Some more jME3 code samples
+
+These code examples are not supported by the core team and we cannot guarantee their correctness:
+
+
+*  <<jme3/user_examples_project#,User Examples Project>> – The jME3 users examples project.
+*  <<jme3/shaderblow_project#,ShaderBlow Project>> – The jME3 users shaders project.
+*  <<jme3/rise_of_mutants_project#,Rise of Mutants Project>> – Rise of Mutants Project by BigBoots Team.
+*  <<jme3/atomixtuts#,atomixtuts>> – Atomix Tutorial Series
+*  link:http://code.google.com/p/street-rally-3d/source/browse/#svn%2Ftrunk%2Fsrc%2Fsr3d[Street rally 3d source code] – A racing game programmed by rhymez.
+
+
+== SDK Documentation
+
+
+image::sdk/jmonkeyplatform-docu-2.png[jmonkeyplatform-docu-2.png,with="420",height="300",align="right"]
+
+
+
+The <<sdk#,jMonkeyEngine SDK>> is our recommended game development environment.
+
+
+*  <<sdk/comic#,jMonkeyEngine SDK - the Comic>>
+*  <<sdk#,SDK Documentation (All editors, plugins, etc)>>
+
+Here are some videos of how the jMonkeyEngine SDK makes your development team's life easier:
+
+
+*  link:http://www.youtube.com/watch?v=nL7woH40i5c[Video: Importing Models]
+*  link:http://www.youtube.com/watch?v=ntPAmtsQ6eM[Video: Scene Composing]
+*  link:http://www.youtube.com/watch?v=DUmgAjiNzhY[Video: Dragging&amp;Dropping Nodes]
+*  link:http://www.youtube.com/watch?v=Feu3-mrpolc[Video: Working with Materials]
+*  link:http://www.youtube.com/watch?v=oZnssg8TBWQ[Video: WebStart Deployment]
+*  link:http://www.youtube.com/watch?v=MNDiZ9YHIpM[Video: Custom Controls]
+*  Read the <<sdk#,SDK documentation>> for details.
+
+
+== Installation
+
+*  <<bsd_license#,Use jMonkeyEngine 3 for free under the BSD License>>
+*  <<jme3/requirements#,Software and hardware requirements>>
+*  <<jme3/features#,All Supported Features>>
+*  link:http://jmonkeyengine.org/wiki/doku.php#Installation[Download jMonkeyEngine 3 SDK]
+
+
+== Feedback
+
+jME3 is in development; if a tutorial doesn't work as expected, try using the latest daily build. If that doesn't “fix it then:
+
+
+*  link:http://code.google.com/p/jmonkeyengine/issues/list?can=2&q=label:Component-Docs[Report a Documentation Task]
+*  link:http://jmonkeyengine.org/wiki/doku.php/report_bugs[Report a Bug]
+*  link:http://jmonkeyengine.org/forums[Ask (and Answer!) Questions on the Forum]
+<tags><tag target="documentation" /><tag target="intro" /><tag target="intermediate" /><tag target="about" /></tags>

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

@@ -0,0 +1,52 @@
+
+
+= Models and Scenes
+
+Like <<shape#,Shape>>s, 3D models are also made up of <<mesh#,Mesh>>es, but models are more complex than Shapes. While Shapes are built into jME3, you typically create models in external 3D Mesh Editors. 
+
+
+
+== Using Models and Scenes with jME3
+
+To use 3D models in a jME3 application:
+
+
+.  Export the 3D model in Ogre XML or Wavefront OBJ format. Export Scenes as Ogre DotScene format.
+.  Save the files into a subdirectory of your jME3 project's `assets` directory.
+.  In your code, you use the <<asset_manager#,Asset Manager>> to load models as <<spatial#,Spatial>>s into a jME application. 
+[source,java]
+----Spatial model = assetManager.loadModel(
+    "Models/MonkeyHead/MonkeyHead.mesh.xml" );----
+.  (For the release build:) Use the jMonkeyEngine SDK to convert models to .j3o format. You don't need this step as long you still develop and test the aplication within the jMonkeyEngine SDK.
+
+
+== Creating Models and Scenes
+
+To create 3D models and scenes, you need a 3D Mesh Editor such as link:http://www.blender.org/[Blender], with an OgreXML Exporter plugin. 
+
+
+*Tip:* Learn how to create link:http://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/UV_Map_Basics[UV textures] for more complex models, it looks more professional. 
+
+
+3D model editors are third-party products, so please consult their documentation for instructions how to use them. Here is an example workflow for Blender users:
+
+
+*  <<jme3/external/blender#,Creating jME3 compatible 3D models in Blender>>
+
+To export your models as Ogre XML meshes with materials:
+
+
+.  Open the menu File &gt; Export &gt; OgreXML Exporter to open the exporter dialog.
+.  In the Export Materials field: Give the material the same name as the model. For example, the model `something.mesh.xml` goes with `something.material`, plus (optionally) `something.skeleton.xml`, and some JPG files.
+.  In the Export Meshes field: Select a target subdirectory of your `assets/Models/` directory. E.g. `assets/Models/something/`.
+.  Activate the following exporter settings: 
+**  Copy Textures: YES
+**  Rendering Materials: YES
+**  Flip Axis: YES
+**  Require Materials: YES
+**  Skeleton name follows mesh: YES
+
+.  Click export.
+
+You can now use the <<sdk#,jMonkeyEngine SDK>> to <<sdk/model_loader_and_viewer#,load and view models>>. You can <<sdk/scene_composer#,create scenes>> from them and write code that loads them into your application. 
+

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

@@ -0,0 +1,15 @@
+
+
+= Recast Navigation
+
+Building a Nav-Mesh for your JME game.
+
+
+
+== About
+
+
+== Setup
+
+
+== Example Code

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

@@ -0,0 +1,230 @@
+
+
+=== Changing the Name of Your APK/Application:
+
+1. Open your project’s properties and navigate to Application+
+
+2. Update the title+
+
+
+
+This has no real effect, however it keeps continuity throughout your app. Actually, this likely renamed the window created to display your app. So, now go change the actual name of your APK:
+
+
+1. Select File View in the left pane of the SDK+
+
+2. Navigate to the mobile/res/values directory and open the strings.xml file+
+
+3. There should be a string tag with the following key pair: name=”app_name”+
+
+4. Replace MyGame with your app’s name and save the file.+
+
+5. In File view, navigate to nbproject and open the project.properties file+
+
+6. Edit the value of application.title to reflect your game’s name (unless step 1/2 above altered this for you)+
+
+
+
+
+=== Changing the APK Icon:
+
+1. Under the File view of your project navigate to mobile/res and add a “drawable” folder if one does not exist.+
+
+2. Add you icon file (png)+
+
+3. Open the Android Manifest file and add the following to your application tag: android:icon=”@drawable/<ICON FILE NAME WITHOUT EXTENSION>”+
+
+4. If you would like multiple size icons, add the following folders:+
+
+
+
+....
+drawable-hdpi (should contain the icon named the same at 72×72 pixels)\\
+drawable-ldpi (should contain the icon named the same at 36×36 pixels)\\
+drawable-mdpi (should contain the icon named the same at 48×48 pixels)\\
+drawable-xhdpi (should contain the icon named the same at 96×96 pixels)\\
+....
+
+
+=== Adding a Splash Screen to your app:
+
+1. Open Android Main Activity, ether through the Important Files list in Project view or in the File view under mobile/src/<package name>/ directory+
+
+2. Add the following line to the MainActivity method:+
+
+
+
+splashPicID = R.drawable.<IMAGE NAME WITHOUT EXTENSION>;
+
+
+3. Add the image the the mobile/res/drawable directory
+
+
+Compiling Google Play Services and Adding it to Your Project:
+
+
+First get the api:
+
+
+1. Download the google play services add-on through the SDK Manager under Extras (named Google Play services)+
+
+2. Copy the directory from where you downloaded it to another location (like JME Projects Folder)+
+
+
+
+
+=== Compile the jar file for use with your project:
+
+1. In the directory you copied, there is an android project file.+
+
+2. In JME’s IDE, open this project+
+
+3. In the General section of the project properties, there is a list of potential Android target platforms. Select the one you are using for your project by clicking on the list (this is not intuitive at all, as the list looks like nothing more than info… not selectable items)+
+
+4. Under the Library section, click the checkbox that is labeled: Is Library+
+
+5. Click Ok and then Clean & Build this project.+
+
+
+
+This will compile the play services all proper like so you can add it to your project. Now, for that step:
+
+
+1. Open your project’s properties.+
+
+2. In the Libraries section, click the “Add JAR/folder” button.+
+
+3. Find and add the jar you compiled above (This can be found in: <COPIED DIR>\libproject\google-play-services_lib\libs\google-play-services.jar+
+
+4. Modify your Android Manifest by adding the following tags under application:+
+
+<meta-data android:name=”com.google.android.gms.games.APP_ID”
+android:value=”@string/app_id” />
+<meta-data android:name=”com.google.android.gms.version”
+android:value=”@integer/google_play_services_version”/>
+5. Add the following tag to your mobile/res/values/integers.xml file (create it if it doesn’t exist):+
+
+<integer name=”google_play_services_version”>4323000</integer>
+6. Clean & Build your project+
+
+
+
+
+=== Adding Play Games Services to Your Project:
+
+1. Download the project from: link:https://github.com/playgameservices/android-samples[https://github.com/playgameservices/android-samples]+
+
+2. In the following directory, you find java files you will need to add to your project:+
+
+
+
+....
+<DOWNLOAD DIR>\android-samples-master\BasicSamples\libraries\BaseGameUtils\src\main\java\com\google\example\games\basegameutils\\
+Grab GameHelper.java and GameHelperUtil.java and add them to the directory you projects Main Activity is in\\
+....
+
+3. In the following directoriy, you find a resource file you will need to add to your project:+
+
+
+
+....
+<DOWNLOAD DIR>\android-samples-master\BasicSamples\libraries\BaseGameUtils\src\main\res\values\\
+Grab the gamehelper_strings.xml into your mobile/res/values folder\\
+....
+
+4. Add the following jar from the Adroid SDK folder to your project as a library:+
+
+
+
+....
+<ANDROID SDK INSTALL DIR>\adt-bundle-windows-x86_64-20131030\sdk\extras\android\support\v4\android-support-v4.jar\\
+....
+
+And this is the basics for setting this up.
+
+
+
+=== Adding AdMob Support to Your Project:
+
+1. Open your Android Manifest and add the following tag update the application tag:+
+
+&lt;activity android:name=”com.google.android.gms.ads.AdActivity” android:configChanges=”keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize”/&gt;+
+
+2. After the application tag, add the following tags:
+&lt;uses-permission android:name=”android.permission.INTERNET”/&gt;+
+
+&lt;uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE”/&gt;+
+
+3. In the onCreate method of your Main Activity, add the following snippet (configure however you like):+
+
+
+
+....
+      adView = new AdView(this);
+      adView.setAdSize(AdSize.FULL_BANNER);
+      adView.setAdUnitId(“<WHATEVER AD UNIT ID YOU ARE ASSIGNED THROUGH THE GOOGLE DEV CONSOLE>”);
+      adView.buildLayer(); 
+      LinearLayout ll = new LinearLayout(this);
+      ll.setGravity(Gravity.BOTTOM);
+      ll.addView(adView);
+      addContentView(ll, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
+....
+
+
+=== Communication Between your Application & Main Activity:
+
+1. Create an interface named something along the lines of JmeToHarness.java
+2. Open your Android Main Activity and implement this interface.
+3. In Main.java of your Application, add the following:
+
+
+....
+ JmeToHarness harness; 
+ public JmeToHarness getHarness() {
+   return this.harness;
+ } 
+ public void setHarnessListener(JmeToHarness harness) {
+    this.harness = harness;
+ }
+ 
+....
+
+4. Add the following snippet to the onCreate method of your Android Main Activity:
+
+
+....
+if (app != null)
+    ((Main)app).setHarnessListener(this);
+    
+....
+
+5. Add error handling if you want it.
+
+
+This bit is ultra useful for calling AdMob changes and Play Games methods (like updating achievements, leader boards, etc, etc)
+
+
+EDIT: Keep this as generic as you possibly can as it should plug &amp; play with iOS &amp; Applets if you keep that in mind. Google Play Services/Play Games Services works for all of the above… soooo… anyways.
+
+
+
+=== Changing the Package Name After Project Creation:
+
+1. Open the project properties of your Application
+2. Navigate to Application &gt; Android and edit the package name.
+
+
+This does absolutely nothing, but help with consistency.
+
+
+So, to actually change the package name, you will want to:
+
+
+1. Open the Android Manifest
+2. Edit the manifest tag key pair: package=”&lt;THE NEW PACKAGE NAME&gt;”
+3. In File view, navigate to nbproject and open the project.properties file
+4. Edit the value of mobile.android.package
+
+
+Take a moment or 4 to navigate through the directory structure in file view and remove any artifacts left from the previous package name build. Alternately, you can run Clean on the project prior to updating the package name.
+

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

@@ -0,0 +1,332 @@
+
+
+= Animation in jME3
+
+In 3D games, you do not only load static 3D models, you also want to be able to trigger animations in the model from the Java code. 
+
+
+
+== Requirements
+
+JME3 only loads and plays animated models, it does not create them. 
+
+
+What is required for an animated model? (<<jme3/terminology#Animation,See also: Animation terminology>>)
+
+
+.  For each model, you have to segment the model into a skeleton (*bone rigging*). 
+.  For each motion, you have to specify how the animation distorts parts of the model (*skinning*).  
+.  For each animation, you have to specify a series of snapshots of how the bones are positioned (*keyframes*).
+.  One model can contain several animations. You give every animation a name when you save it in the mesh editor.
+
+Unless you download free models, or buy them from a 3D artist, you must create your animated models in an *external mesh editor* (for example, Blender) yourself.
+
+
+*  <<sdk/blender#,Converting Blender Models to JME3 (.J3o files)>>
+*  link:http://www.youtube.com/user/aramakara[Video Series: Creating models in Blender, OgreMax, 3dsMax]
+*  link:http://www.youtube.com/watch?v=NdjC9sCRV0s[Video: Creating and Exporting OgreXML Animations from Blender 2.61 to JME3 ]
+*  link:https://docs.google.com/fileview?id=0B9hhZie2D-fENDBlZDU5MzgtNzlkYi00YmQzLTliNTQtNzZhYTJhYjEzNWNk&hl=en[Scene Workflow: Exporting OgreXML scenes from Blender to JME3]
+*  link:https://docs.google.com/leaf?id=0B9hhZie2D-fEYmRkMTYwN2YtMzQ0My00NTM4LThhOTYtZTk1MTRlYTNjYTc3&hl=en[Animation Workflow: Create Animated UV-Mapped OgreXML Models in Blender, and use them in JME3]
+*  link:http://www.youtube.com/watch?v=IDHMWsu_PqA[Video: Creating Worlds with Instances in Blender]
+
+What is required in your JME3-based Java class?
+
+
+*  One Animation Control per animated model
+*  As many Animation Channels per Control as you need to play your animations. In simple cases one channel is enough, sometimes you need two or more Channels per model to play gestures and motions in parallel.
+
+
+== Code Samples
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestSpatialAnim.java[TestSpatialAnim.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestBlenderAnim.java[TestBlenderAnim.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestBlenderObjectAnim.java[TestBlenderObjectAnim.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestOgreAnim.java[TestOgreAnim.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestOgreComplexAnim.java[TestOgreComplexAnim.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/model/anim/TestCustomAnim.java[TestCustomAnim.java]
+
+
+== Controlling Animations
+
+
+=== The Animation Control
+
+Create one `com.jme3.animation.AnimControl` object in your JME3 application for each animated model that you want to control. You have to register each animated model to one of these Animation Controls. The control object gives you access to the available animation sequences in the model.  
+
+
+[source,java]
+----
+  AnimControl playerControl; // you need one Control per model
+  Node player = (Node) assetManager.loadModel("Models/Oto/Oto.mesh.xml"); // load a model
+  playerControl = player.getControl(AnimControl.class); // get control over this model
+  playerControl.addListener(this); // add listener
+----
+
+=== Animation Channels
+
+An Animation Control has several Animation Channels (`com.jme3.animation.AnimChannel`). Each channel can play one animation sequence at a time. 
+
+
+There often are situations where you want to run several animation sequences at the same time, e.g. “shooting while walking or “boxing while jumping. In this case, you create several channels, assign an animation to each, and play them in parallel. 
+
+
+[source,java]
+----
+  AnimChannel channel_walk = playerControl.createChannel();
+  AnimChannel channel_jump = playerControl.createChannel();
+  ...
+----
+To reset a Control, call `control.clearChannels();`
+
+
+
+== Animation Control Properties
+
+The following information is available for an AnimControl.
+
+[cols="2", options="header"]
+|===
+
+a|AnimControl Property
+a|Usage
+
+a|createChannel()
+a|Returns a new channel, controlling all bones by default.
+
+a|getNumChannels()
+a|The number of channels registered to this Control.
+
+a|getChannel(0)
+a|Gets individual channels by index number. At most `getNumChannels()`.
+
+a|clearChannels()
+a|Clear all channels in this control.
+
+a|addListener(animEventListener) +
+removeListener(animEventListener) +
+clearListeners() 
+a|Adds or removes listeners to receive animation related events.
+
+|===
+[cols="2", options="header"]
+|===
+
+a|AnimControl Property
+a|Usage
+
+a|setAnimations(aniHashMap)
+a|Sets the animations that this AnimControl is capable of playing. The animations must be compatible with the skeleton given in the constructor.
+
+a|addAnim(boneAnim) +
+removeAnim(boneAnim)
+a|Adds or removes an animation from this Control.
+
+a|getAnimationNames()
+a|A String Collection of names of all animations that this Control can play for this model.
+
+a|getAnim(“anim)
+a|Retrieve an animation from the list of animations.
+
+a|getAnimationLength(“anim)
+a|Returns the length of the given named animation in seconds
+
+|===
+[cols="2", options="header"]
+|===
+
+a|AnimControl Property
+a|Usage
+
+a|getSkeleton()
+a|The Skeleton object controlled by this Control.
+
+a|getTargets()
+a|The Skin objects controlled by this Control, as Mesh array.
+
+a|getAttachmentsNode(“bone)
+a|Returns the attachment node of a bone. Attach models and effects to this node to make them follow this bone's motions.
+
+|===
+
+
+== Animation Channel Properties
+
+The following properties are set per AnimChannel.
+
+[cols="2", options="header"]
+|===
+
+a|AnimChannel Property
+a|Usage
+
+a|setLoopMode(LoopMode.Loop); 
+a| From now on, the animation on this channel will repeat from the beginning when it ends. 
+
+a|setLoopMode(LoopMode.DontLoop); 
+a| From now on, the animation on this channel will play once, and the freeze at the last keyframe. 
+
+a|setLoopMode(LoopMode.Cycle); 
+a| From now on, the animation on this channel will play forward, then backward, then again forward, and so on. 
+
+a|setSpeed(1f); 
+a| From now on, play this animation slower (&lt;1f) or faster (&gt;1f), or with default speed (1f). 
+
+a|setTime(1.3f); 
+a| Fast-forward or rewind to a certain moment in time of this animation. 
+
+|===
+
+The following information is available for a channel.
+
+[cols="2", options="header"]
+|===
+
+a|AnimChannel Property
+a|Usage
+
+a|getAnimationName()
+a|The name of the animation playing on this channel. Returns `null` when no animation is playing.
+
+a|getLoopMode()
+a|The current loop mode on this channel. The returned com.jme3.animation enum can be LoopMode.Loop, LoopMode.DontLoop, or LoopMode.Cycle.
+
+a|getAnimMaxTime()
+a|The total length of the animation on this channel. Or `0f` if nothing is playing.
+
+a|getTime()
+a|How long the animation on this channel has been playing. It returns `0f` if the channel has not started playing yet, or a value up to getAnimMaxTime().
+
+a|getControl()
+a|The AnimControl that belongs to this AnimChannel.
+
+|===
+
+Use the following methods to add or remove individual bones to an AnimChannel. This is useful when you play two animations in parallel on two channels, and each controls a subset of the bones (e.g. one the arms, and the other the legs).
+
+[cols="2", options="header"]
+|===
+
+a|AnimChannel Methods
+a|Usage
+
+a|addAllBones()
+a|Add all the bones of the model's skeleton to be influenced by this animation channel. (default)
+
+a|addBone(“bone1) +
+addBone(bone1)
+a|Add a single bone to be influenced by this animation channel.
+
+a|addToRootBone(“bone1) +
+addToRootBone(bone1) 
+a|Add a series of bones to be influenced by this animation channel: Add all bones, starting from the given bone, to the root bone.
+
+a|addFromRootBone(“bone1) +
+addFromRootBone(bone1) 
+a|Add a series of bones to be influenced by this animation channel: Add all bones, starting from the given root bone, going towards the children bones.
+
+|===
+
+
+== Playing Animations
+
+Animations are played by channel. *Note:* Whether the animation channel plays continuously or only once, depends on the Loop properties you have set.
+
+[cols="2", options="header"]
+|===
+
+a|Channel Method
+a|Usage
+
+a|channel_walk.setAnim(“Walk,0.50f); 
+a| Start the animation named “Walk on channel channel_walk. +
+The float value specifies the time how long the animation should overlap with the previous one on this channel. If set to 0f, then no blending will occur and the new animation will be applied instantly.
+
+|===
+
+*Tip:* Use the AnimEventLister below to react at the end or start of an animation cycle.
+
+
+
+=== Usage Example
+
+In this short example, we define the space key to trigger playing the “Walk animation on channel2.
+
+
+[source,java]
+----
+  public void simpleInitApp() {
+    ...
+    inputManager.addMapping("Walk", new KeyTrigger(KeyInput.KEY_SPACE));
+    inputManager.addListener(actionListener, "Walk");
+    ...
+  }
+
+  private ActionListener actionListener = new ActionListener() {
+    public void onAction(String name, boolean keyPressed, float tpf) {
+      if (name.equals("Walk") && !keyPressed) {
+        if (!channel2.getAnimationName().equals("Walk")) {
+          channel2.setLoopMode(LoopMode.Loop);
+          channel2.setAnim("Walk", 0.50f);
+        }
+      }
+    }
+  };
+----
+
+== Animation Event Listener
+
+A jME3 application that contains animations can implement the `com.jme3.animation.AnimEventListener` interface.
+
+
+[source,java]
+----public class HelloAnimation extends SimpleApplication
+                     implements AnimEventListener { ... }----
+This optional Listener enables you to respond to animation start and end events, onAnimChange() and onAnimCycleDone().
+
+
+
+=== Responding to Animation End
+
+The onAnimCycleDone() event is invoked when an animation cycle has ended. For non-looping animations, this event is invoked when the animation is finished playing. For looping animations, this event is invoked each time the animation loop is restarted.
+
+
+You have access to the following objects:
+
+
+*  The Control to which the listener is assigned.
+*  The animation channel being played.
+*  The name of the animation that has just finished playing.
+
+[source,java]
+----
+  public void onAnimCycleDone(AnimControl control, AnimChannel channel, String animName) {
+    // test for a condition you are interested in, e.g. ...
+    if (animName.equals("Walk")) {
+      // respond to the event here, e.g. ...
+      channel.setAnim("Stand", 0.50f);
+    }
+  }
+----
+
+=== Responding to Animation Start
+
+The onAnimChange() event is invoked every time before an animation is set by the user to be played on a given channel (`channel.setAnim()`).
+
+
+You have access to the following objects
+
+
+*  The Control to which the listener is assigned.
+*  The animation channel being played.
+*  The name of the animation that will start playing.
+
+[source,java]
+----
+  public void onAnimChange(AnimControl control, AnimChannel channel, String animName) {
+    // test for a condition you are interested in, e.g. ...
+    if (animName.equals("Walk")) {
+      // respond to the event here, e.g. ...
+      channel.setAnim("Reset", 0.50f);
+    }
+  }
+----

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

@@ -0,0 +1,42 @@
+
+
+== Anisotropic Filtering for Textures
+
+Anisotropic Filtering is very important for Desktop Games and their textures. Most games use AnisotropicFiltering = 4/8/16. It sharpens your textures under different Angle View. 
+Anisotropy makes a performance draw back about 10-40 fps, but the result looks much better.
+
+
+See Example: link:http://i.imgur.com/0yiv9.jpg[http://i.imgur.com/0yiv9.jpg]
+
+image::jme3/advanced/anisotropy_example_mifth_01.jpg[anisotropy_example_mifth_01.jpg,with="360",height="900",align="right"]
+
+
+
+JME has DEFAULT AnisotropicFiltering = 0. So, if you make a game for Windows/Linux/Mac.. you need to set the Anisotropic Filtering more than 0.
+
+
+Example how to set AnisotropicFiltering = 4 for all textures:
+
+
+[source,java]
+----
+        AssetEventListener asl = new AssetEventListener() {
+            public void assetLoaded(AssetKey key) {
+//                throw new UnsupportedOperationException("Not supported yet.");
+            }
+
+            public void assetRequested(AssetKey key) {
+                if (key.getExtension().equals("png") || key.getExtension().equals("jpg") || key.getExtension().equals("dds")) {
+                    System.out.println(key.getExtension());
+                    TextureKey tkey = (TextureKey) key;
+                    tkey.setAnisotropy(8);
+                }
+            }
+
+            public void assetDependencyNotFound(AssetKey parentKey, AssetKey dependentAssetKey) {
+//                throw new UnsupportedOperationException("Not supported yet.");
+            }
+        };
+        
+        assetManager.addAssetEventListener(asl);
+----

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

@@ -0,0 +1,260 @@
+
+
+= Application States
+
+The `com.jme3.app.state.AppState` class is a customizable jME3 interface that allows you to control the global game logic, the overall game mechanics. (To control the behaviour of a Spatial, see <<jme3/advanced/custom_controls#,Custom Controls>> instead. Controls and AppStates can be used together.)
+
+
+
+== Overview
+
+
+=== Use Case Examples
+
+There are situations during your game development where you think:
+
+
+*  Mouse and key inputs are handled differently in-game versus in the main menu. Can I group a set of input handler settings, and activate and deactivate them all in one step?  
+*  I have the in-game scene, and a character editor, and a Captain's Quarters screen. Can I group a set of nodes and behaviours, and swap them in and out in one step?
+*  When I pause the game, I want the character's “idle animation to continue, but all other loops and game events should stop. How do I define what happens when the game is paused/unpaused? 
+*  I have a conditional block that takes up a lot of space in my simpleUpdate() loop. Can I wrap up this block of code, and switch it on and off in one step?
+*  Can I package everything that belongs in-game, and everything that belongs to the menu screen, and switch between these two “big states in one step? 
+
+You can! This is what AppStates are there for. An AppState class is subset of (or an extension to) your application. Every AppState class has access to all fields in your main application (AssetManager, ViewPort, StateManager, InputManager, RootNode, GuiNode, etc) and hooks into the main update loop. An AppState can contain:
+
+
+*  a subset of class fields, functions, methods (game state data and accessors), 
+*  a subset of +++<abbr title="Graphical User Interface">GUI</abbr>+++ elements and their listeners, 
+*  a subset of input handlers and mappings, 
+*  a subset of nodes that you load and attach to the rootNode, 
+*  a subset of conditional actions that you branch to in the simpleUpdate() loop, 
+*  a subset of other AppStates and Controls
+*  … or combinations thereof. 
+
+
+=== Supported Features
+
+Each AppState lets you define what happens to it in the following situations:
+
+
+*  *The AppState is initialized:* You load and initialize game data, InputHandlers, AppStates and Controls and attach nodes. +
+The AppState executes its own simpleInitApp() method when it is attached, so to speak.
+*  *The AppState has been enabled (unpaused):* This toggles a boolean isEnabled() to true. Here you attach nodes and listeners that should become active while it's running. 
+*  *While the AppState is running/paused:* You can poll isEnabled() to define paused and unpaused game behaviour in the update() loop. In update(), you poll and modify the game state, modify the scene graph, and trigger events. Test if `!isEnabled()`, and write code that skips the running sections of this AppState's `update()` loop. +
+Each AppState has its own update loop, which hooks into the main simpleUpdate() loop (callback). 
+*  *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>+++
+
+
+
+=== Usage
+
+To implement game logic:
+
+
+.  Create one AbstractAppState instance for each set of game mechanics. 
+.  Implement game behaviour in the AppState's update() method.
+**  You can pass custom data as arguments in the constructor.
+**  The AppState has access to everything inside the app's scope via the Application `app` object.
+
+.  Create and attach the AppState to the AppStateManager (`stateManager.attach(myAppState);`) and initialize it.
+.  Enable and disable (unpause and pause) the AppStates that you need during the game.
+.  Detach the AppState from the AppStateManager (`stateManager.detach(myAppState);`) and clean it up.
+
+When you add several AppStates to one Application and activate them, their initialize() methods and update() loops are executed in the order in which the AppStates were added to the AppStateManager.
+
+
+
+=== Code Samples
+
+JME3 comes with a BulletAppState that implements Physical behaviour (using the jBullet library). You, for example, could write an Artificial Intelligence AppState to control all your enemy units. Existing examples in the code base include:
+
+
+*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-bullet/src/common/java/com/jme3/bullet/BulletAppState.java[BulletAppState] controls physical behaviour in PhysicsControl'ed Spatials.
+*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/app/state/TestAppStates.java[TestAppStates.java] an example of a custom AppState
+**  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/app/state/RootNodeState.java[RootNodeState.java]
+
+
+
+== AppState
+
+The AppState interface lets you initialize sets of objects, and hook a set of continously executing code into the main loop.
+
+[cols="2", options="header"]
+|===
+
+a|AppState Method
+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;----
+
+a|cleanup()
+a|This method is executed after you remove the AppState from the game. Here you implement clean-up code for when this state is detached. You can modify the scene graph from here (e.g. detach nodes).
+
+a|update(float tpf)
+a|Here you implement the behaviour that you want to hook into the simpleUpdate() loop while this state is attached to the game. You can modify the scene graph from here.
+
+a|isInitialized()
+a|Your implementations of this interface should return the correct respective boolean value. (See AbstractAppState)
+
+a|setActive(true) +
+setActive(false)
+a|Temporarily enables or disables an AppState. (See AbstractAppState) 
+
+a|isActive()
+a|Test whether AppState is enabled or disabled. Your implementation should consider the boolean. (See AbstractAppState)
+
+a|stateAttached(asm) +
+stateDetached(asm)
+a|The AppState knows when it is attached to, or detached from, the AppStateManager, and triggers these two methods. Don't modify the scene graph from here! (Typically not used.) 
+
+a|render(RenderManager rm)
+a|Renders the state, plus your optional customizations. (Typically not used.)
+
+a|postRender()
+a|Called after all rendering commands are flushed, including your optional customizations. (Typically not used.)
+
+|===
+
+
+== AbstractAppState
+
+The AbstractAppState class already implements some common methods (`isInitialized(), setActive(), isActive()`) and makes creation of custom AppStates a bit easier. We recommend you extend AbstractAppState and override the remaining AppState methods: `initialize(), setEnabled(), cleanup()`.
+
+
+Definition:
+
+
+[source,java]
+----public class MyAppState extends AbstractAppState {
+
+    private SimpleApplication app;
+
+    private Node x = new Node("x");  // some custom class fields...    
+    public Node getX(){ return x; }  // some custom methods... 
+    
+    @Override
+    public void initialize(AppStateManager stateManager, Application app) {
+      super.initialize(stateManager, app); 
+      this.app = (SimpleApplication)app;          // cast to a more specific class
+      
+      // init stuff that is independent of whether state is PAUSED or RUNNING
+      this.app.getRootNode().attachChild(getX()); // modify scene graph...
+      this.app.doSomething();                     // call custom methods...
+   }
+    
+   @Override
+    public void cleanup() {
+      super.cleanup();
+      // unregister all my listeners, detach all my nodes, etc...
+      this.app.getRootNode().detachChild(getX()); // modify scene graph...
+      this.app.doSomethingElse();                 // call custom methods...
+    }
+
+    @Override
+    public void setEnabled(boolean enabled) {
+      // Pause and unpause
+      super.setEnabled(enabled);
+      if(enabled){
+        // init stuff that is in use while this state is RUNNING
+        this.app.getRootNode().attachChild(getX()); // modify scene graph...
+        this.app.doSomethingElse();                 // call custom methods...
+      } else {
+        // take away everything not needed while this state is PAUSED
+        ...
+      }
+    }
+    
+    // Note that update is only called while the state is both attached and enabled.
+    @Override
+    public void update(float tpf) {
+      // do the following while game is RUNNING
+      this.app.getRootNode().getChild("blah").scale(tpf); // modify scene graph...
+      x.setUserData(...);                                 // call some methods...
+    }
+    
+}----
+
+== Pausing and Unpausing
+
+You define what an AppState does when Paused or Unpaused, in the `setEnabled()` and `update()` methods. Call `myState.setEnabled(false)` on all states that you want to pause. Call `myState.setEnabled(true)` on all states that you want to unpause.
+
+
+
+== AppStateManager
+
+The com.jme3.app.state.AppStateManager holds the list of AppStates for an application. AppStateManager ensures that active AppStates can modify the scene graph, and that the update() loops of active AppStates is executed. There is one AppStateManager per application. You typically attach several AppStates to one AppStateManager, but the same state can only be attached once.
+
+[cols="2", options="header"]
+|===
+
+a|AppStateManager Method
+a|Usage
+
+a|hasState(myState)
+a|Is AppState object 'myState' attached?
+
+a|getState(MyAppState.class)
+a|Returns the first attached state that is an instance of a subclass of `MyAppState.class`.
+
+|===
+
+The AppStateManager's `render(), postRender(), cleanup()` methods are internal, ignore them, users never call them directly.
+
+
+*  If a detached AppState is attached then initialize() will be called on the following render pass.
+*  If an attached AppState is detached then cleanup() will be called on the following render pass.
+*  If you attach an already-attached AppState then the second attach is a no-op and will return false.
+*  If you both attach and detach an AppState within one frame then neither initialize() or cleanup() will be called, although if either is called both will be.
+*  If you both detach and then re-attach an AppState within one frame then on the next update pass its cleanup() and initialize() methods will be called in that order.
+
+
+== Best Practices
+
+
+=== Communication Among AppStates
+
+You can only access other AppStates (read from and write to them) from certain places: From a Control's update() method, from an AppState's update() method, and from the SimpleApplication's simpleUpdate() loop. Don't mess with the AppState from other places, because from other methods you have no control over the order of modifications; the game can go out of sync because you can't know when (during which half-finished step of another state change) your modification will be performed.
+
+
+You can use custom accessors to get data from AppStates, to set data in AppStates, or to trigger methods in AppStates.
+
+
+[source,java]
+----this.app.getStateManager().getState(MyAppState.class).doSomeCustomStuffInThisState();----
+
+=== Initialize Familiar Class Fields
+
+To access class fields of the SimpleApplication the way you are used to, initialize them to local variables, as shown in the following AppState template:
+
+
+[source,java]
+----
+private SimpleApplication app;
+private Node              rootNode;
+private AssetManager      assetManager;
+private AppStateManager   stateManager;
+private InputManager      inputManager;
+private ViewPort          viewPort;
+private BulletAppState    physics;
+
+public class MyAppState extends AbstractAppState {
+  @Override
+  public void initialize(AppStateManager stateManager, Application app) {
+    super.initialize(stateManager, app);
+    this.app = (SimpleApplication) app; // can cast Application to something more specific
+    this.rootNode     = this.app.getRootNode();
+    this.assetManager = this.app.getAssetManager();
+    this.stateManager = this.app.getStateManager();
+    this.inputManager = this.app.getInputManager();
+    this.viewPort     = this.app.getViewPort();
+    this.physics      = this.stateManager.getState(BulletAppState.class);
+  }
+}
+----

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

@@ -0,0 +1,394 @@
+
+
+= Simple AppStates Demo
+
+
+
+
+
+
+
+= THIS DEMO IS OUT OF DATE AND NEEDS CORRECTING FOR NOW PLEASE SEE
+
+ link:http://jmonkeyengine.org/wiki/doku.php/jme3:advanced:application_states[http://jmonkeyengine.org/wiki/doku.php/jme3:advanced:application_states]
+
+
+Note: this tutorial needs to be fixed and is currently not correct.  One should almost never override stateDetached and stateAttached… and should certainly never do anything scene related in them.
+
+
+This demo is a simple example of how you use AppStates to toggle between a StartScreen and a SettingsScreen (press RETURN) while the game is paused, and start the game by switching to a GameRunning state (press BACKSPACE). 
+
+
+There are four files, Main.java, GameRunningState.java, StartScreenState.java, SettingsScreenState.java. 
+
+
+
+== Main.java
+
+[source,java]
+----
+package chapter04.appstatedemo;
+
+import com.jme3.app.SimpleApplication;
+import com.jme3.input.KeyInput;
+import com.jme3.input.controls.ActionListener;
+import com.jme3.input.controls.KeyTrigger;
+import com.jme3.input.controls.Trigger;
+
+/**
+ * This demo shows a simple "game" with three AppStates. Instead of game content, 
+ * it just displays three cubes on different backgrounds.
+ * <ul>
+ * <li>StartScreenState: This state is enabled 
+ *     when the user starts the application, or the the game is paused. 
+ *     Press BACKSPACE to return to the game, press RETURN to go to Settings.</li>
+ * <li>GameRunningState: This state shows the game content and is enabled while the game is running. 
+ *     Press BACKSPACE to pause and return to the start screen.</li>
+ * <li>SettingsScreenState: This Settings screen state can be reached from the start screen
+ *     Press RETURN to toggle it on and off.</li>
+ * </ul>
+ */
+public class Main extends SimpleApplication {
+
+  private Trigger pause_trigger = new KeyTrigger(KeyInput.KEY_BACK);
+  private Trigger save_trigger = new KeyTrigger(KeyInput.KEY_RETURN);
+  private boolean isRunning = false; // starts at startscreen
+  private GameRunningState gameRunningState;
+  private StartScreenState startScreenState;
+  private SettingsScreenState settingsScreenState;
+
+  
+  /** Start the jMonkeyEngine application */
+  public static void main(String[] args) {
+    Main app = new Main();
+    app.start();
+  }
+
+  /**
+   * initialize the scene here
+   */
+  @Override
+  public void simpleInitApp() {
+    setDisplayFps(false);
+    setDisplayStatView(false);
+
+    gameRunningState    = new GameRunningState(this);
+    startScreenState    = new StartScreenState(this);
+    settingsScreenState = new SettingsScreenState(this);
+
+    stateManager.attach(startScreenState);
+
+    inputManager.addMapping("Game Pause Unpause", pause_trigger);
+    inputManager.addListener(actionListener, new String[]{"Game Pause Unpause"});
+    inputManager.addMapping("Toggle Settings", save_trigger);
+    inputManager.addListener(actionListener, new String[]{"Toggle Settings"});
+  }
+  
+  private ActionListener actionListener = new ActionListener() {
+    public void onAction(String name, boolean isPressed, float tpf) {
+      System.out.println("key" + name);
+      if (name.equals("Game Pause Unpause") && !isPressed) {
+        if (isRunning) {
+          stateManager.detach(gameRunningState);
+          stateManager.attach(startScreenState);
+          System.out.println("switching to startscreen...");
+
+        } else {
+          stateManager.detach(startScreenState);
+          stateManager.attach(gameRunningState);
+          System.out.println("switching to game...");
+        }
+        isRunning = !isRunning;
+      } else if (name.equals("Toggle Settings") && !isPressed && !isRunning) {
+        if (!isRunning && stateManager.hasState(startScreenState)) {
+          stateManager.detach(startScreenState);
+          stateManager.attach(settingsScreenState);
+          System.out.println("switching to settings...");
+        } else if (!isRunning && stateManager.hasState(settingsScreenState)) {
+          stateManager.detach(settingsScreenState);
+          stateManager.attach(startScreenState);
+          System.out.println("switching to startscreen...");
+        }
+      }
+    }
+  };
+
+  @Override
+  public void simpleUpdate(float tpf) {}
+
+}
+ 
+----
+
+== GameRunningState.java
+
+[source,java]
+----
+package chapter04.appstatedemo;
+
+import com.jme3.app.Application;
+import com.jme3.app.SimpleApplication;
+import com.jme3.app.state.AbstractAppState;
+import com.jme3.app.state.AppStateManager;
+import com.jme3.asset.AssetManager;
+import com.jme3.font.BitmapFont;
+import com.jme3.font.BitmapText;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.Vector3f;
+import com.jme3.renderer.ViewPort;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.shape.Box;
+
+/**
+ * A template how to create an Application State. This example state simply
+ * changes the background color depending on the camera position.
+ */
+public class GameRunningState extends AbstractAppState {
+
+  private ViewPort viewPort;
+  private Node rootNode;
+  private Node guiNode;
+  private AssetManager assetManager;
+  private Node localRootNode = new Node("Game Screen RootNode");
+  private Node localGuiNode = new Node("Game Screen GuiNode");
+  private final ColorRGBA backgroundColor = ColorRGBA.Blue;
+
+  public GameRunningState(SimpleApplication app){
+    this.rootNode     = app.getRootNode();
+    this.viewPort      = app.getViewPort();
+    this.guiNode       = app.getGuiNode();
+    this.assetManager  = app.getAssetManager();  
+  }
+
+  @Override
+  public void initialize(AppStateManager stateManager, Application app) {
+    super.initialize(stateManager, app);
+
+    /** Load this scene */
+    viewPort.setBackgroundColor(backgroundColor);
+
+    Box mesh = new Box(Vector3f.ZERO, 1, 1, 1);
+    Geometry geom = new Geometry("Box", mesh);
+    Material mat = new Material(assetManager,
+            "Common/MatDefs/Misc/Unshaded.j3md");
+    mat.setColor("Color", ColorRGBA.Green);
+    geom.setMaterial(mat);
+    geom.setLocalTranslation(1, 0, 0);
+    localRootNode.attachChild(geom);
+
+    /** Load the HUD*/
+    BitmapFont guiFont = assetManager.loadFont(
+            "Interface/Fonts/Default.fnt");
+    BitmapText displaytext = new BitmapText(guiFont);
+    displaytext.setSize(guiFont.getCharSet().getRenderedSize());
+    displaytext.move(10, displaytext.getLineHeight() + 20, 0);
+    displaytext.setText("Game running. Press BACKSPACE to pause and return to the start screen.");
+    localGuiNode.attachChild(displaytext);
+  }
+
+  @Override
+  public void update(float tpf) {
+    /** the action happens here */
+    Vector3f v = viewPort.getCamera().getLocation();
+    viewPort.setBackgroundColor(new ColorRGBA(v.getX() / 10, v.getY() / 10, v.getZ() / 10, 1));
+    rootNode.getChild("Box").rotate(tpf, tpf, tpf);
+  }
+  
+  @Override
+  public void stateAttached(AppStateManager stateManager) {
+    rootNode.attachChild(localRootNode);
+    guiNode.attachChild(localGuiNode);
+    viewPort.setBackgroundColor(backgroundColor);
+  }
+
+  @Override
+  public void stateDetached(AppStateManager stateManager) {
+    rootNode.detachChild(localRootNode);
+    guiNode.detachChild(localGuiNode);
+
+  }
+
+}
+----
+
+== SettingsScreenState.java
+
+[source,java]
+----
+package chapter04.appstatedemo;
+
+import com.jme3.app.Application;
+import com.jme3.app.SimpleApplication;
+import com.jme3.app.state.AbstractAppState;
+import com.jme3.app.state.AppStateManager;
+import com.jme3.asset.AssetManager;
+import com.jme3.font.BitmapFont;
+import com.jme3.font.BitmapText;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.Vector3f;
+import com.jme3.renderer.ViewPort;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.shape.Box;
+
+/**
+ * A template how to create an Application State. This example state simply
+ * changes the background color depending on the camera position.
+ */
+public class SettingsScreenState extends AbstractAppState {
+
+  private ViewPort viewPort;
+  private Node rootNode;
+  private Node guiNode;
+  private AssetManager assetManager;
+  private Node localRootNode = new Node("Settings Screen RootNode");
+  private Node localGuiNode = new Node("Settings Screen GuiNode");
+  private final ColorRGBA backgroundColor = ColorRGBA.DarkGray;
+
+  public SettingsScreenState(SimpleApplication app) {
+    this.rootNode     = app.getRootNode();
+    this.viewPort      = app.getViewPort();
+    this.guiNode       = app.getGuiNode();
+    this.assetManager  = app.getAssetManager();
+  }
+
+  @Override
+  public void initialize(AppStateManager stateManager, Application app) {
+    super.initialize(stateManager, app);
+
+    /** Load this scene */
+    viewPort.setBackgroundColor(backgroundColor);
+
+    Box mesh = new Box(new Vector3f(-1, -1, 0), .5f, .5f, .5f);
+    Geometry geom = new Geometry("Box", mesh);
+    Material mat = new Material(assetManager,
+            "Common/MatDefs/Misc/Unshaded.j3md");
+    mat.setColor("Color", ColorRGBA.Red);
+    geom.setMaterial(mat);
+    geom.setLocalTranslation(1, 0, 0);
+    localRootNode.attachChild(geom);
+
+    /** Load the HUD */
+    BitmapFont guiFont = assetManager.loadFont(
+            "Interface/Fonts/Default.fnt");
+    BitmapText displaytext = new BitmapText(guiFont);
+    displaytext.setSize(guiFont.getCharSet().getRenderedSize());
+    displaytext.move(10, displaytext.getLineHeight() + 20, 0);
+    displaytext.setText("Settings screen. Press RETURN to save "
+            + "and return to start screen.");
+    localGuiNode.attachChild(displaytext);
+  }
+
+  @Override
+  public void update(float tpf) {
+     /** the action happens here */
+  }
+
+  @Override
+  public void stateAttached(AppStateManager stateManager) {
+    rootNode.attachChild(localRootNode);
+    guiNode.attachChild(localGuiNode);
+    viewPort.setBackgroundColor(backgroundColor);
+  }
+
+  @Override
+  public void stateDetached(AppStateManager stateManager) {
+    rootNode.detachChild(localRootNode);
+    guiNode.detachChild(localGuiNode);
+  }
+  
+}
+----
+
+== StartScreenState.java
+
+[source,java]
+----
+package chapter04.appstatedemo;
+
+import com.jme3.app.Application;
+import com.jme3.app.SimpleApplication;
+import com.jme3.app.state.AbstractAppState;
+import com.jme3.app.state.AppStateManager;
+import com.jme3.asset.AssetManager;
+import com.jme3.font.BitmapFont;
+import com.jme3.font.BitmapText;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.Vector3f;
+import com.jme3.renderer.ViewPort;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.shape.Box;
+
+/**
+ * A template how to create an Application State. This example state simply
+ * changes the background color depending on the camera position.
+ */
+public class StartScreenState extends AbstractAppState {
+
+  private ViewPort viewPort;
+  private Node rootNode;
+  private Node guiNode;
+  private AssetManager assetManager;
+  private Node localRootNode = new Node("Start Screen RootNode");
+  private Node localGuiNode = new Node("Start Screen GuiNode");
+  private final ColorRGBA backgroundColor = ColorRGBA.Gray;  
+
+public StartScreenState(SimpleApplication app){
+    this.rootNode     = app.getRootNode();
+    this.viewPort     = app.getViewPort();
+    this.guiNode      = app.getGuiNode();
+    this.assetManager = app.getAssetManager();  
+  }
+
+  @Override
+  public void initialize(AppStateManager stateManager, Application app) {
+    super.initialize(stateManager, app);
+    
+    /** Init this scene */
+    viewPort.setBackgroundColor(backgroundColor);
+
+    Box mesh = new Box(new Vector3f(-1,1,0), .5f,.5f,.5f);
+    Geometry geom = new Geometry("Box", mesh);
+    Material mat = new Material(assetManager,
+            "Common/MatDefs/Misc/Unshaded.j3md");
+    mat.setColor("Color", ColorRGBA.Yellow);
+    geom.setMaterial(mat);
+    geom.setLocalTranslation(1, 0, 0);
+    localRootNode.attachChild(geom);
+
+    /** Load a HUD */
+    BitmapFont guiFont = assetManager.loadFont(
+            "Interface/Fonts/Default.fnt");
+    BitmapText displaytext = new BitmapText(guiFont);
+    displaytext.setSize(guiFont.getCharSet().getRenderedSize());
+    displaytext.move( 10, displaytext.getLineHeight() + 20,  0);
+    displaytext.setText("Start screen. Press BACKSPACE to resume the game, "
+            + "press RETURN to edit Settings.");
+    localGuiNode.attachChild(displaytext);
+  }
+
+  @Override
+  public void update(float tpf) {
+    /** the action happens here */
+  }
+
+  @Override
+  public void stateAttached(AppStateManager stateManager) {
+    rootNode.attachChild(localRootNode);
+    guiNode.attachChild(localGuiNode);
+    viewPort.setBackgroundColor(backgroundColor);
+  }
+
+  @Override
+  public void stateDetached(AppStateManager stateManager) {
+    rootNode.detachChild(localRootNode);
+    guiNode.detachChild(localGuiNode);
+  }
+  
+}
+----

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

@@ -0,0 +1,256 @@
+
+
+= AssetManager
+
+By assets we mean multi-media files, such as 3D models, materials, textures, scenes, custom shaders, music and sound files, and custom fonts. JME3 has an integrated asset manager that helps you keep your project assets organized. Think of the asset manager as the filesystem of your game, independent of the actual deployment platform. By default, store your assets in the `MyGame/assets/ ` directory of your project.
+
+
+Advantages of the AssetManager:
+
+
+*  The paths stay the same, no matter whether the game runs on Windows, Mac, Linux, etc!
+*  The AssetManager automatically caches and optimizes the handling of OpenGL objects. +
+For example, the same textures are not uploaded to the graphics card multiple times when multiple models use them.
+*  The <<sdk/default_build_script#,default build script>> automatically bundles the contents of the `assets` directory into the executable. 
+
+Advanced users can write a custom build and packaging script, and can register custom paths to the AssetManager, but this is up to you then. 
+
+
+
+==== Context
+
+[source]
+----
+jMonkeyProjects/MyGame/assets/    # You store assets in subfolders here! <------
+jMonkeyProjects/MyGame/build/     # SDK generates built classes here (*)
+jMonkeyProjects/MyGame/build.xml  # You customize Ant build script here
+jMonkeyProjects/MyGame/nbproject/ # SDK stores default build.xml and meta data (*)
+jMonkeyProjects/MyGame/dist/      # SDK generates executable distribution here (*)
+jMonkeyProjects/MyGame/src/       # You store Java sources here
+jMonkeyProjects/MyGame/test/      # You store test classes here (optional)
+(*) Managed by jMonkeyEngine SDK -- don't edit!
+----
+See also <<jme3/intermediate/best_practices#,Best Practices>>.
+
+
+
+== Usage
+
+The `assetManager` object is an com.jme3.asset.AssetManager instance that every com.jme3.app.Application can access. It maintains a root that also includes your project's classpath by default, so you can load any asset that's on the classpath, that is, the top level of your project directory. 
+
+
+You can use the inherited `assetManager` object directly, or use the accessor `app.getAssetManager()`.
+
+
+Here is an example how you load assets using the AssetManager. This lines loads a default Material from the built-in `Common/` directory:
+
+
+[source,java]
+----Material mat = (Material) assetManager.loadAsset(
+    new AssetKey("Common/Materials/RedColor.j3m"));----
+This Material is “somewhere in the jME3 JAR; the default Asset Manager is configured to handle a `Common/…` path correctly, so you don't have to specify the whole path when referring to built-in assets (such as default Materials).
+
+
+Additionally, you can configure the Asset Manager and add any path to its root. This means, you can load assets from any project directory you specify. The next example shows how you load assets from your project's assets directory.
+
+
+
+== Asset Directory
+
+By default, jME3 searches for models in a directory named `assets`. 
+
+
+`assets``assets`
+
+
+This is our recommended directory structure for storing assets:
+
+
+[source]
+----
+jMonkeyProjects/MyGame/src/...           # Packages, .java source code.
+jMonkeyProjects/MyGame/assets/...        # The assets directory:
+jMonkeyProjects/MyGame/assets/Interface/   # .font, .jpg, .png, .xml
+jMonkeyProjects/MyGame/assets/MatDefs/     # .j3md
+jMonkeyProjects/MyGame/assets/Materials/   # .j3m
+jMonkeyProjects/MyGame/assets/Models/      # .j3o
+jMonkeyProjects/MyGame/assets/Scenes/      # .j3o
+jMonkeyProjects/MyGame/assets/Shaders/     # .j3f, .vert, .frag
+jMonkeyProjects/MyGame/assets/Sounds/      # .ogg, .wav
+jMonkeyProjects/MyGame/assets/Textures/    # .jpg, .png; also .mesh.xml+.material, .mtl+.obj, .blend (!) 
+----
+These subdirectories are just the most common examples. 
+
+
+`assets`
+
+
+*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`
+
+
+
+== Example Code: Loading Assets
+
+Creating a material instance with the definition “Unshaded.j3md:
+
+
+[source,java]
+----
+Material mat_brick = new Material( 
+    assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+----
+Applying a texture to the material:
+
+
+[source,java]
+----
+mat_brick.setTexture("ColorMap", 
+    assetManager.loadTexture("Textures/Terrain/BrickWall/BrickWall.jpg"));
+----
+Loading a font:
+
+
+[source,java]
+----
+guiFont = assetManager.loadFont("Interface/Fonts/Default.fnt");
+----
+Loading a model:
+
+
+[source,java]
+----
+Spatial ninja = assetManager.loadModel("Models/Ninja/Ninja.mesh.xml");
+----
+Loading a scene from an Ogre3D dotScene file stored inside a zip:
+
+
+[source,java]
+----
+assetManager.registerLocator("town.zip", ZipLocator.class);
+Spatial scene = assetManager.loadModel("main.scene");
+rootNode.attachChild(scene);
+----
+Alternatively to ZipLocator, there is also a HttpZipLocator that can stream models from a zip file online:
+
+
+[source,java]
+----
+assetManager.registerLocator("http://jmonkeyengine.googlecode.com/files/wildhouse.zip", 
+                             HttpZipLocator.class);
+Spatial scene = assetManager.loadModel("main.scene");
+rootNode.attachChild(scene);
+----
+jME3 also offers a ClasspathLocator, ZipLocator, FileLocator, HttpZipLocator, and UrlLocator (see `com.jme3.asset.plugins`). 
+
+
+“
+
+
+
+== Common AssetManager Tasks
+[cols="2", options="header"]
+|===
+
+a| Task? 
+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);----
+
+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");
+teapot.setMaterial(mat);
+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);----
+
+|===
+
+
+== NullPointerException: Cannot locate resource?
+
+*Problem:*
+
+
+My game runs fine when I run it right from the jMonkeyEngine SDK. But when I run the stand-alone executables (.jar, .jnlp .exe, .app), a DesktopAssetManager error message occurs in the console, and it quits?
+
+
+[source]
+----com.jme3.asset.DesktopAssetManager loadAsset
+WARNING: Cannot locate resource: Scenes/town/main.scene
+com.jme3.app.Application handleError
+SEVERE: Uncaught exception thrown in Thread[LWJGL Renderer Thread,5,main]
+java.lang.NullPointerException
+----
+*Reason:*
+
+
+If you use the default build script, *original models and scenes (.mesh.xml, .obj, .blend, .zip), are excluded* from the distribution automatically. A stand-alone executable includes converted *.j3o files* (models and scenes) only. The default build script makes sure to bundle existing .j3o files in the distribution, but you need to remember to convert the models (from mesh.xml–&gt;.j3o, or .obj–&gt;.j3o, etc) yourself. 
+
+
+*Solution*
+
+
+Before building the executable, you must use the jMonkeyEngine SDK's context menu action to <<sdk/model_loader_and_viewer#,convert 3D models to .j3o binary format>>.
+
+
+.  Save your original models (.mesh.xml, .scene, .blend, or .obj files, plus textures) into `assets/Textures/`. (!)
+.  Open the jME3 project in the jMonkeyEngine SDK.
+.  Browse to the `assets` directory in the Projects window. 
+.  Right-click an original model in `assets/Textures/`, and choose “Convert to JME3 binary.
+.  The converted file appears in the same directory as the original file. It has the same name and a `.j3o` suffix. 
+.  Move the .j3o file into the `assets/Models/` or `assets/Scenes/` directory.
+.  Use the assetManager's `load()` method to load the `.j3o` file.
+
+This ensures that the model's Texture paths keep working between your 3D mesh editor and JME3.
+
+
+<<sdk/default_build_script#,default build script>>
+
+
+
+== Asset Handling For Other IDEs: Codeless Projects
+
+*Problem:*
+
+
+I use another IDE than jMonkeyEngine SDK for coding (Eclipse, IntelliJ, text editor). Where is my `asset` folder and .j3o converter?
+
+
+*Solution:*
+
+
+You can code in any IDE, but you must create a so-called codeless project in the jMonkeyEngine SDK to maintain assets. *A code-less jMonkeyEngine project does not meddle with your sources or custom build scripts.* You merely use it to convert models to .j3o binaries. 
+
+
+.  Create your (Eclipse or whatever) project as you like.
+.  Create a directory in your project folder and name it, for example, `assets`. +
+Store your assets there as described above.
+.  Download and install the jMonkeyEngine SDK.
+.  In the SDK, go to File → Import Projects → External Project Assets.
+.  Select your (Eclipse or whatever) project and your assets folder in the Import Wizard.
+.  You can now open this (Eclipse or whatever) project in the jMonkeyEngine SDK. +
+Convert assets as described above.
+
+<<jme3/advanced/save_and_load#,BinaryExporter>>
+
+
+
+

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

@@ -0,0 +1,284 @@
+
+
+== Atom framework Introduction
+
+*Hi Monkeys,*
+
+
+*Atom framework for game developing in Java. Powered by JME3.*
+
+
+*Atom* framework which on top of JME3 and have some features like AI, Scripting, Database, VirtualReallity, Trigger, Multiplayer…(more below)  to make developing game process in JME3 much more easier!
+
+
+
+<<jme3/atomixtuts#,atomixtuts>>
+
+
+
+=== Open Source
+
+Atom Core : The AtomCore source code is hosted in Googlecode
+
+
+Googlecode: link:https://code.google.com/p/atom-game-framework/[https://code.google.com/p/atom-game-framework/]
+
+
+Github: link:https://github.com/atomixnmc/atom-game-framework[https://github.com/atomixnmc/atom-game-framework]
+
+
+Wiki: link:https://code.google.com/p/atom-game-framework/wiki/[https://code.google.com/p/atom-game-framework/wiki/]
+
+
+
+=== Documentations:
+
+<<jme3/advanced/atom_framework/design#, Detailed architecture designs >>
+
+
+<<jme3/advanced/atom_framework/docs#, Detailed documentation >>
+
+
+<<jme3/advanced/atom_framework/comparison#, Detailed comparison>>
+
+
+
+=== Idea & Buzz
+
+*Better, more freedom, more fun!*
+
+
+From +++<strike>UDK and Unity</strike>+++ 's battle field, I've dreamt about making even better game engine with the help of my 2 fav technologies - *Java* and *opensource*.
+
+
+JME3 and Netbean combination are the most brighten idea I 've seen in years. I think it deserve a better reputation worldwide.
+
+
+
+==== Initial Ideas:
+
+*  Ease the learning curve
+*  Fun play/create game like kids in a sandbox
+*  Framework for games and apps(3D) 
+*  Nextgen techs
+
+
+==== Why call it Atom?
+
+link:https://en.wikipedia.org/wiki/Atom[https://en.wikipedia.org/wiki/Atom]
+
+
+Yes, this is for game developing. But in its heart is future's technologies. 
+
+
+....
+ Atom Etymology: Devive the thing as small as you can, than compose it into a thing again.
+....
+[quote]
+____
+ The same in programming, after all, modulize is to be integrated again! That really is the core idea of Atom framework, use the most simple primitives to compose the bigger, bigger matter! Every where, small tiny, fastest, embed inside others, stick together well…Take a look in Atom Ex <<jme3/advanced/atom_framework/atomex#,atomex>>, you will see the picture more clearly.
+____
+
+The most conceptual inspiration for Atom framework is project link:http://ptolemy.eecs.berkeley.edu/index.htm[http://ptolemy.eecs.berkeley.edu/index.htm] . Unfortunately Ptolemy is in “for research only area and its direction toward the much large scale than game developing. That's why Atom framework was born with the learnt architecture from Ptolemy. 
+
+[quote]
+____
+ The Ptolemy project studies modeling, simulation, and design of concurrent, real-time, embedded systems. The focus is on assembly of concurrent components. The key underlying principle in the project is the use of well-defined models of computation that govern the interaction between components. A major problem area being addressed is the use of heterogeneous mixtures of models of computation
+____
+[quote]
+____
+ Atom is designed to MAKE concurrent, real-time, embedded systems and GAMES. So it focus more in code generation, profile, monitoring; focus more in graphics, physics, player experience…etc. Underlying, it borrow quite a bunch of concept that built in Ptolemy.
+____
+
+
+=== Features
+
+* Atom framework Highlights*
+
+
+*  Flexible: Game | simulations centric but not forced!
+*  Modular: Dependency injection along with Component injection
+*  Parallel: Embrace parallel computing
+*  Next gen: Come with Bleeding edge technologies and powers of Java languages
+*  Cloud ready: Scale to web and distributed computing
+*  With ease: +++<abbr title="Graphical User Interface">GUI</abbr>+++ Tools everywhere, almost zero config need
+
+Full Features list
+
+
+*  Cross game genre framework for JME3
+**  <<jme3/advanced/atom_framework/atomcore#,General stage - world ; game play and cycle>>
+**  <<jme3/advanced/atom_framework/atomcore/entitysystem#,General Entity framework>>
+**  <<jme3/advanced/atom_framework/atomcore/event#,General Event framework>>
+**  <<jme3/advanced/atom_framework/atomcore/config#,Intuitive config framework  >>- toward zero-config approach
+**  <<jme3/advanced/atom_framework/atomcore/actor#,Actor and interactive agents, workers>>
+**  <<jme3/advanced/atom_framework/atomcore/execution#,Execution and monitor>>
+
+*  Network | Web ready
+**  Web scale support 
+**  <<jme3/advanced/atom_framework/atomcore/net#, Network &amp; Messaging framework>>
+**  <<jme3/advanced/atom_framework/atomcore/league#, Social foundation framework>>
+
+*  Additional to JME3 features (as libraries or toolkits)
+**  <<jme3/advanced/atom_framework/atomcore/fx#, UltimateEffects >>
+***  <<jme3/advanced/atom_framework/atomcore/particles#, UltimateParticles>>
+***  <<jme3/advanced/atom_framework/atomcore/sprite#, Cross dimension model >>
+***  <<jme3/advanced/atom_framework/atomcore/filters#, Filters >>
+
+**  <<jme3/advanced/atom_framework/atomcore/cinematic#, Cinematic >>
+**  <<jme3/advanced/atom_framework/atomcore/gui#, General extensible GUI with CSS>>
+**  <<jme3/advanced/atom_framework/atomexasset#, Ultimate asset pipeline>>
+**  <<jme3/advanced/atom_framework/atomanim#, Ultimate animation framework>>
+**  <<jme3/advanced/atom_framework/atomelight#, Extra rendering methods>>
+
+
+
+=== Architecture and components
+
+Here are its architecture and components.
+
+
+
+
+
+
+==== Atom Core Libraries
+
+*  *<<jme3/advanced/atom_framework/atomcore#, AtomCore>>* : addition to JME3 core packages. 
+**  Cross game-genre elements: stage, cycle, entity, logic, trigger, event, config; 
+**  Managers: Advanced assets manager, dependecy injection, factory, scripting, basic DB..; 
+**  Common case: Common state, common scenerio, common UIs… 
+**  More Buzz? <<jme3/advanced/atom_framework/atomcore#, AtomCore documentation >>
+
+*  *<<jme3/advanced/atom_framework/atomscripting#, Atom Scripting>>* Base technology for use Groovy (potentional Scala, Jython..) as JME game scripting language… 
+**  Provide Test bed enviroment, thread-safe and intelligent Groovy swing component to extend the SDK in seconds
+**  More Buzz? <<jme3/advanced/atom_framework/atomscripting#, Atom Scripting>>
+
+*  *<<jme3/advanced/atom_framework/ai#, Atom AI>>* : a “framework to bring AI to jME3 game (also means real-time application)! But it's awesome in its own way. 
+**  Focus in AI coding, creating, testing, simulating, profiling in 3d enviroments.
+**  Come with tools as SDK plugins!
+**  Check <<jme3/advanced/atom_framework/ai#, Atom AI wiki>> for more buzz
+
+
+
+==== Ingame editor facilities and kits
+
+*  <<jme3/advanced/atom_framework/atomeditor#,Atom Editor>>: sotiphicated in-game editor application and +++<abbr title="Application Programming Interface">API</abbr>+++ for 3D games modelled toward netbean platform architecture. [In constrast with SimpleGameEditor project].
+*  <<jme3/advanced/atom_framework/atom2deditor#,Atom 2D Editor>>: for 2D games.
+*  *<<jme3/advanced/atom_framework/codegen#,Code Gen>>*: a “framework that intend to become the base technologies for all generation related techs in the Atom framework. <<jme3/advanced/atom_framework/codegen#,codegen>>
+**  Focus in provide general and abstract way to modeling|design game|real-time app concept and object, source codes. 
+**  Its first attempt to become a GLSL, Groovy generator, then become a Logic, source code generator… 
+**  Come with tools as SDK plugins!
+
+*  *<<jme3/advanced/atom_framework/citygen#,City Gen>>*: a “framework at first try to be a city generator, then grow up to be fullfill every geometric generating operations in 3D.
+**  Focus in “Level generator with 3d models, blueprint and geometric shapes, such as dugeon, city, rivers, mountain, trees…
+**  Can corporate with Code gen and other geometric libs to become a generative 3D editor…
+**  Come with tools as SDK plugins!
+
+
+
+==== Atom SDK
+
+*  *Atom SDK* : Expansion for current functions and features of the jME SDK on top of Netbean platform for desktop Swing based editing, more intuitive more user friendly and suchs.
+**  Full List? <<jme3/advanced/atom_framework/atomsdk#,atomsdk>>
+
+*  *TeeheeComposer* : Act as the base editor for video, cinematic, audio, effects, facial composer… anything require time-base keyframed or unlinear editing like sequences.
+**  An almighty composer, think about 3DSMax or Adobe After Effect in 3D
+**  Come with a lot of tools for the SDK : <<jme3/advanced/atom_framework/teehee#,teehee>>
+***  Cinematic composer
+***  Dialogue composer
+***  Effect composer
+***  Particle composer
+***  Animation composer
+
+
+*  *RPGCreator* : Despite of its name, its not just for Role playing game! 
+**  Provide functions to create| test| config basic game with these key elements : characters| stories| skills| items| modes| regions… almost every game genre has them embeded partly ( cross game genre)
+**  Come with tools as SDK plugins! <<jme3/advanced/atom_framework/rpgcreator#,rpgcreator>>
+
+*  *Nextgen Tools*
+**  Facial tools : Think FaceFX for JME :p <<jme3/advanced/atom_framework/facial#,facial>>
+**  Character customization management tools : Smart way to organize and corporate your assets, config, database and code for CC <<jme3/advanced/atom_framework/cc#,cc>>
+**  Vitural reality tools : Toolset for corporate vitural reality artifact in your app <<jme3/advanced/atom_framework/vr#,vr>>
+**  MMORPG tools : Toolset for creating of a MMORPG game's component and all its management structure. Epic! <<jme3/advanced/atom_framework/mmorpgtools#,mmorpgtools>>
+**  Human Simulation tools: Think advanced locomotion and AI (like Mechanim of Unity) multiply 10. In fact, it's quite similar with tool from Autodesk that simulations social beheviours of human characters. Epic! <<jme3/advanced/atom_framework/humansim#,humansim>>
+
+
+
+==== AtomEx Libraries and platform
+
+*  *Atom Ex* : addition to Atom framework which make its much more modulizable, extensible and enterprise ready. Distributed computing, web based, database… much more.
+**  More Buzz? <<jme3/advanced/atom_framework/atomex#, AtomEx documentation >>
+
+
+
+=== Vision
+
+
+==== Java,... again??!
+
+Yeah, it was long time ago, you quit learning java because java gaming is a dead end.
+
+
+But Android come to play, and the the market are open so freaking big that even companies live with their C++ code base want to take advantage of the new wave…
+
+
+Recently Java has so much improvements and then JME3 enchant the talents all around the world to develop the master peices of software!
+
+
+
+==== But did we chasing after them?
+
+No, we are not. We are going ahead of them with all the techniques from the almightly open-source.
+
+
+Java communities are much more open and helpful than any of those Microsoft, Apple, UDK, Unity,… evils… Let's make a fairplay at last!
+
+
+
+==== Can we win?
+
+The time will tell… but at least, we once gain give the power to the hands of the people, not just some rich and intelligent people, that's the most critical point!
+
+
+
+=== Project status
+
+If you interest in contribute to Atom framework open-sourced project, here is the status of the project in 2014 and some mile stones it want to reach in the future.
+
+
+<<jme3/advanced/atom_framework/status#,Atom framework open-sourced project Status - 2014>>
+
+
+
+=== Other open-source dependencies
+
+Actually it use directly/indirectly various projects of JME3 great contributors and open source projects:
+
+
+*  AI from @Sploreg,@shirkit and mine
+*  VirtualReallity integrated with OpenCV, JavaCV : @noncom + mine
+*  ShaderBlow from @mifth
+*  SpriteEngine @dansion
+*  Forestor from @androlo
+*  Multiplayer on top of MirrorMonkey, Kryonet, Arianne, ThreeRings, …
+*  MonkeyZone code which I believe written by @normen @nehon and core guys :p
+*  Database using Cayenne, Depot
+*  … other contributors 
+
+( I will add them later :p please forgive if I can't remember your name immediately )
+…
+
+
+_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.
+
+
+<<jme3/atomixtuts#, Atomix Series of game making>>
+
+
+GOTO <<jme3/advanced/atom_framework/docs#,Detailed Atom framework Documentation>>
+

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

@@ -0,0 +1,287 @@
+
+
+== AtomAI
+
+Hi,
+
+
+This is the wiki for Atom AI framework.
+
+
+
+image::http///blogs.ifsworld.com/wp-content/uploads/2012/11/AI-lowres.jpg[AI-lowres.jpg,with="200",height="",align="right"]
+
+
+
+
+=== Questions and Answers
+
+*Question:* What's the h#$ll is AI or why should I bother in this thingy anyway emoji:
+
+
+*Answer:* It's big, over-complicated and also attractive subject in Game developing.. emoji: emoji:sunglasses
+
+
+*Question:* What can be use in my game?
+
+
+*Answer:* Everything… You can use this lib to:
+
+
+*   solve the common path finding, 
+*  let your creature know how to think and learn, 
+*  direct your vehicle the way to move, 
+*  your camera to interact with the screen, 
+*  teach your characters to walk/ talk/ shoot/ trading… 
+*  You can also use it in various type of simulations and 
+*  even try to solve a mathematic problem.
+
+*Question:* Sound wonderful…? But wait… It should be soooooooo freaking big and heavy, is it *real-time* shit?
+
+
+*Answer:* Yes, partly… Some parts are real heavy for real time computing. They just can be used in non real time application or few kind of games. Others apx 60% are designed well enough to run in real time, and also provided with JME examples. It also comes with architectures/ functions that can config, optimize, balance, cache, and batch it selfs for real-time applications…
+
+
+*Question:* Eh… Universal solution can not be true…
+
+
+*Answer:* Let's me explain. Consider this a warper of every good open-source java AI libraries you can name out and hook in to JME architecure (AppState, Sptial, Entity, Control, Update cycle…etc). Under the hood, I use Guice| OSGi |Felix to dynamicly link/bind them, when you need it. The full explaination you will find below.
+
+
+*Question:* Nice, I want to try it?
+
+
+*Answer:* Everything is here at once, sir/ madam !
+More questions ? Not convinced yet? Go to <<FAQ,FAQ>>
+
+
+
+=== Introducing Atom AI framework
+
+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>>
+
+
+
+=== Idea & Buzz
+
+*  It contains warpers for various java AI libraries build on top of light-weight, configable module architecture and provide the way to hook seamlessly to jME3 games. 
+*  It's also come up with a lot of working examples in several game genre (RTS, RPG, FPS, Sport,…). 
+*  40% of components, AI algorimth are rewritten by the author (@atomix) to be light-weight and usable in real-time application.
+*  Tend to be used in production application and games and suppose to support broadest cases it can.
+*  Users can use the pieces to build up their own AI part of their games and apps
+*  Pushed to future java techs: dependencies injection, parallel as its core…
+
+
+=== Features
+
+(T) means additional Tools are supported
+
+
+(C) means with examples cases
+
+
+(E) means use| depend on external libs 
+
+
+
+
+
+
+
+
+
+==== Framework
+
+*  Modulize (E)
+*  Dependency free (E)
+*  Configable , balancable , profilable , level of detail (T)
+*  Paralel (E)
+
+
+==== Data Structure
+
+*  State (T)
+*  Tree (T)
+*  Graph (T)(E)
+*  Geometric (T)(E)
+
+
+==== General algorimth and Support techs
+
+*  Optimizing problem(E)
+*  Constraint programming(E)
+*  Fuzzy logic(E)
+*  Probability
+*  Genetic (T)(E)
+*  Neutral network (T)(E)
+*  Rule base (T)(E)
+*  Scripting (T)
+
+
+==== General AI Techs
+
+*  Movement
+**  Kinematic
+**  Physics embed
+**  Steering
+***  Boid
+***  Swarm
+
+**  Formation
+
+*  FSM , HFSM , FFSM for AI (T)
+*  Searching
+**  Path finding 
+***  algorimth: A Star, theta Star 
+***  space: Grid, Hex, Tris, Polys, 3D Block, 3D Terrain, NavMesh, points cloud/, graphs… [more]
+***  generate methods: navmesh gen,jump points, choke points, viewset points, … [more]
+***  re-touch methods: smooth, reduce, prunning, time-wise, cahing, progessive
+***  highly extensible, hookable, configableready to use as corporated with lower and higher techs
+
+**  General path finding
+***  Iterative deepending
+***  Some academic stuffs …
+
+
+*  Reasoning
+**  Decision Tree 
+**  Minimax
+**  Some academic stuffs …
+
+*  Planning
+**  Goal base
+
+*  Problem sovling
+*  Learning
+
+
+==== Character AI
+
+
+===== Human
+
+*  Chatbot  (T)(E)(C)
+*  Dialoge (T)(C)
+*  Emotion (T)(C)
+*  Facial (T)(C)
+*  Voice (T)(E)
+*  Gesture (T)(E)
+*  CommonSense (C)
+*  Common Human AI usecases (C)
+
+
+===== Animal
+
+
+=== Architecture and components
+
+Here are its <<jme3/advanced/atom_framework/ai/architecture/architecture#,Architecture>> and <<jme3/advanced/atom_framework/ai/components/components#,Components>>.
+
+
+
+
+
+
+=== Vision
+
+As the framework grown up, I will bring more unit tests and example cases.
+
+
+Also it should has even better integration with the JME SDK and other Netbean's plugins like (weka, neuphons…). Corporate with Code gen, it's can easily replace Alice, Manson,etc…  as much better 3D non-coding enviroment and one day maybe become the most advanced AI simulation enviroment on earth! 
+
+
+
+=== FAQ
+
+*Question*: Why warpers?
+
+
+*Answer*: Not reinventing the wheel, trust in good opensource project, broader use caces, broader user… And last but not least, it's just work!
+
+'''
+
+*Question*: Why java 1.5+?
+
+
+*Answer* : Consider this lib is a push to java techs and java's game techs. The user are forced to get familiar with the changing world… Yes, AI is a rapid changing subject and we (java game devs) should keep up.
+
+'''
+
+*Question*: Why f$#kin heavy and not light-weight, real-time, etc???
+
+
+*Answer*: This libs provide some features which just optimized enough to run in “quite high performance machine. But it also have sotiphicated methods to config it self. Consider this key feature to keep in mind. Get fit!
+
+'''
+
+*Question*: Big jar?
+
+
+*Answer*: Nope, consider not too big… thanks to Guice, size &lt; 6MBs and can even smaller if you compile it your self and cut the unneccesary things. In some case you want to use *ALL* the features, the whole dependencies will take about *78MB* and *45MB* for the SDK plugins! And Maven should be to used to get every artifacts!
+
+'''
+
+*Question*: Documentations and javadoc?
+
+
+*Answer* : On its way, the orginal author (me, @atomix) are slow (busy) , volunteers are welcome! Also read all the external wel-documented open source libs <<jme3/advanced/atom_framework/ai/libs#, Full list here>> that this lib depend on are quite enough. Cause its idiom is simple.
+
+'''
+
+*Question*: I have ideas?
+
+
+*Answer* : Tell me , @atomix in the forum.
+
+
+
+=== Other open-source dependencies
+
+As said, even if I try to rewriten some parts that most critical for real time game, I cannot against the ideas of including every good functions of other libs. So, I provide good way to communicate between them and the way to link them on demand…
+
+
+Let name the libs can be used:
+As category
+
+
+*  Neutral Network
+*  Machine Learning
+*  Search
+*  Constraint programming
+*  Geometry constraint
+*  Human language processing
+**  Chatbot
+
+
+
+== Documentation
+
+
+=== Basic
+
+
+=== Examples & Usecases
+
+
+=== API
+
+
+== Alternatives
+
+
+=== Open sources
+
+
+=== Commercial
+
+
+=== Toolset
+
+
+== Researches
+
+Go to <<jme3/advanced/atom_framework/researches#,researches>>
+

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

@@ -0,0 +1,148 @@
+
+
+== AtomAI
+
+AtomAI is an innovative framework for doing AI for simulations and interactive applications, focus in Games!
+
+
+
+=== Technologies
+
+AtomAI built up by bleeding-edge of AI technologies based in lastest researches. Underlying, it depends in extensible framework to leverage maximum Java language in spirit of Atom framework.
+
+
+Many parts of AtomAI are very innovative and actually release the developer from low level concerning and save a lot of time redo common usecases implementations; without errors.
+
+
+
+=== Dependencies
+
+AtomAI depend a lot in good AI opensource projects
+
+
+
+==== Java DataStructures & Mechanisms
+
+
+===== Javolution
+
+link:http://javolution.org/[http://javolution.org/]
+
+
+....
+ Because real-time programming requires a time-predictable standard library. Javolution real-time goals are simple: To make your application faster and more time predictable!
+....
+
+Javolution solve some fundamental real-time problems with innovative technologies. Javolution is one of core dependencies of AtomCore and so AtomAI. 
+
+
+
+===== Guava & Guice
+
+Two google opensource projects that make Java developer's life easier.
+
+
+
+===== Apache Commons
+
+Lang
+
+
+BeanUtils 
+
+
+Math
+
+
+Logging
+
+
+
+
+
+
+===== XXL
+
+link:http://code.google.com/p/xxl/[http://code.google.com/p/xxl/]
+
+
+....
+ XXL is a Java library that contains a rich infrastructure for implementing advanced query processing functionality. The library offers low-level components like access to raw disks as well as high-level ones like a query optimizer. On the intermediate levels, XXL provides a demand-driven cursor algebra, a framework for indexing and a powerful package for supporting aggregation.
+....
+
+XXL already solved a lot of problems in spatial, relational and metadata… Upon that base, AtomAI focus in higher level of abstraction like Graph, State, Tree; Flow, Stream, Load balance;  later focus more in AI stuffs without worry about lower levels.
+
+
+
+===== Qi4j
+
+link:http://qi4j.org/[http://qi4j.org/]
+
+
+....
+ is a framework for domain centric application development, including evolved concepts from Aspect Oriented Programming, Dependency Injection and Domain Driven Design.
+....
+
+....
+ Qi4j™ is an implementation of Composite Oriented Programming, using the standard Java platform, without the use of any pre-processors or new language elements. Everything you know from Java still applies and you can leverage both your experience and toolkits to become more productive with Composite Oriented Programming today.
+....
+
+Qi4j offers a way to config the system by layers and entities. More over, Entity-Composite (with relasionship enable) compare to Entity-components is a better way to compose things.
+
+
+
+===== RxJava
+
+link:https://github.com/Netflix/RxJava[https://github.com/Netflix/RxJava]
+
+
+....
+ Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.
+....
+
+RxJava already provided mechanisms for composing asynchronous and event-based programs. AtomAI then focus in design the flows of events of agents. This is a win-win scenario for boths.
+
+
+
+==== Scripting
+
+
+===== Groovy
+
+Groovy leverage Java in a very elegent way. Make itself the most valid candidate to being a scripting language for Java and AtomAI to construct a very flexible framework. AtomAI also provide better mechanisms to automatic tasks and tools, give developer more power in editing scripts and actions.
+
+
+
+==== AI Model and source structure
+
+
+===== AIMA
+
+link:http://code.google.com/p/aima-java/[http://code.google.com/p/aima-java/]
+
+
+....
+ Java implementation of algorithms from Norvig and Russell's Artificial Intelligence - A Modern Approach 3rd Edition
+ 
+....
+
+is de-facto for AI techs. AtomAI *modify* and *add implementations* to AIMA-java that intergrate deeply with above technologies, make AIMA the most complete, powerful and open java AI framework.
+
+
+
+===== Choco
+
+link:https://github.com/chocoteam/choco3[https://github.com/chocoteam/choco3]
+
+
+....
+  Choco3 is an open-source Java library for Constraint Programming. 
+  Choco3 comes with:
+....
+
+....
+  various type of variables (integer, boolean, set, graph and real),
+  various state-of-the-art constraints (alldifferent, count, nvalues, etc.),
+  various search strategies, from basic ones (first_fail, smallest, etc.) to most complex (impact-based and activity-based search),
+  explanation-based engine, that enables conflict-based back jumping, dynamic backtracking and path repair
+....

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

@@ -0,0 +1,30 @@
+
+
+== Atom2D
+
+Atom2D
+
+
+
+=== Datastructure
+
+
+=== Algorimths
+
+
+=== Geometry
+
+
+=== Assets
+
+
+=== Graphics
+
+
+=== Scenegraph2D
+
+
+=== Tools
+
+(Swing)
+

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

@@ -0,0 +1,13 @@
+
+
+== AtomEditor
+
+Provide +++<abbr title="Application Programming Interface">API</abbr>+++ and implementation for “reactive in-game editor in JME3 and Atom framework. 
+
+
+Inspired by: 
+
+
+Netbean: link:https://netbeans.org/[https://netbeans.org/]
+LightTable: link:http://www.lighttable.com/[http://www.lighttable.com/]
+

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

@@ -0,0 +1,3 @@
+
+
+== Atom Animation

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

@@ -0,0 +1,513 @@
+
+
+== AtomCore Introduction
+
+AtomCore is the main component of Atom framework.
+
+
+This is the detailed documentation of AtomCore module architecture, design decisions, implementations and real usecases, examples, resources.
+
+
+Source: link:https://code.google.com/p/atom-game-framework/source/browse/AtomCore/[https://code.google.com/p/atom-game-framework/source/browse/AtomCore/]
+
+
+Javadoc: 
+
+
+Issues:
+
+
+Quick links: _Read if you know ready know the basic_
+
+
+<<jme3/advanced/atom_framework/atomcore/cycle#,AtomCore Cycle>>
+
+
+<<jme3/advanced/atom_framework/design/patterns#,AtomCore patterns>>
+
+
+<<jme3/advanced/atom_framework/atomcore/algorithms#,AtomCore algorithms>>
+
+
+
+== Architecture Design
+
+Atom philosophy is “Minimal, “Only one.
+
+
+As a software modeler, you always need more than one thing to decribe your solutions. Atom try to compact them into mimimal sets and if possible, only one piece of consistent but flexible design.
+
+
+As a developer, you may find it easy to adapt and extend the framework to suite your games and purpose.
+
+
+Now talk about the most primitive “Core design of the framework is a “Relationship between the “Core and the “Container. This also the most important concept of philosophy of the universe, sciences and of course programming.
+
+
+AtomCore leverages Java programming with concepts and ultilities for various pairs of Core-Container (common in game development) such as: Actor &amp; Stage, Player &amp; League, Task &amp; Manager, Worker &amp; Thread, Entity &amp; Context, UI &amp; Layout, Stream &amp; Pipeline, Pipeline &amp; Topology…
+
+
+Beside of those common basis pairs, collections, graphs and other datastructure, executions, pattern and behaviours are also supported!
+
+
+The details of those techniques will be listed below.
+
+
+
+=== The core features:
+
+Features of AtomCore
+
+
+*  Cross game-genre elements: stage, cycle, entity, logic, trigger, event, config;
+*  Managers and management: Advanced assets manager, IOC, AOP, dependecy injection, factory, scripting, basic DB..;
+*  Common case: Common state, common scenerio, common UIs…
+
+Below you will read about how each feature is implemented in AtomCore.
+
+
+
+==== Cross game-genre elements
+
+From an abstraction level, a Game- a special kind of software (almost always):
+
+
+*  composed by Entities, and their Stage; 
+*  where Actions happen in a Cycle, procedure Events;
+
+A little bit more detailed, Gameplay is the way player play the Game, has:
+
+
+*  Logic:
+**  Trigger: in which Conditions, active some appropriate Action, as primitive brick.
+**  Rule: the laws, restrictions form the game rule which player, entities obey.
+
+*  Routines: Situations/ Events/ Actions that happen in the game Cycle.
+**  Story/Cinematic mode: When player just watch the game like a movie.
+**  Interactive mode: When player interact with the game world
+
+*  Control: The way player handle their entities
+*  League: 
+**  Player, Matchs, Groups and their infos &amp; activities
+**  Single: Infos, score, rewards stick to an individual 
+**  Multi: The way players join, left, make friend and interactive and play together…
+
+*  Status: Way to pause/continue , save/load current game
+
+The game “software should be published in specific enviroment called Context, it then has:
+
+
+*  Configurations : appropriate settings for specific enviroment, device.
+*  Data : appropriate size and format
+
+
+===== Around Bean
+
+
+
+
+In <<jme3/advanced/atom_framework/atomcore/beans#,AtomCore Bean>> are leverage in a few ways:
+
+
+*  Modeling
+*  Generating
+*  Binding
+*  Mapping / Morphing
+*  Instropecting
+*  Managed
+
+
+===== Attend Cycle
+
+In JME3 we almost see the things work like this, the “almighty” Cycle:
+
+
+link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:advanced:update_loop[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:advanced:update_loop]
+
+
+.  Input listeners respond to mouse clicks and keyboard presses – Input handling
+.  Update game state:
+..  Update overall game state – Execute Application States
+...  User code update – Execute simpleUpdate() method
+...  Logical update of entities – Execute Custom Controls
+
+
+.  Render audio and video
+..  Application States rendering.
+..  Scene rendering.
+..  User code rendering – Execute simpleRender() method.
+
+.  Repeat loop.
+
+The reason this cycle exists is because of JME3 application tied strictly with monotholic processing method, and the main convict is OpenGL.
+
+
+In Atom, is not actually the case!! Atom try to connect various parts of facilities in networks and try to run as independent-parallel as it can. Cycle defined as a pre-ordered routine is not suiable with the work of parallel processing and enterprise… That's why a sotiphicated customable-expandable “cycle is the heart to Atom framework which made it a solid replacement of “old JME3 cycle. 
+
+
+Read more details in AtomCore's Cycle.
+
+
+<<jme3/advanced/atom_framework/atomcore#,atomcore>>
+
+
+
+===== As core of a whole Enterprise
+
+As a long term follower of Spring (one of Atom inspiration) : 
+link:http://spring.io/[http://spring.io/]  …
+link:http://en.wikipedia.org/wiki/Spring_framework[http://en.wikipedia.org/wiki/Spring_framework]
+
+
+I learnt few things,eventually Spring is for Enterprise, so most of its features is accessed through AtomEx, but AtomCore will have some of its goods to be integrated later.
+
+
+<<jme3/advanced/atom_framework/atomex#,atomex>>
+
+
+
+=== AtomCore concepts
+
+....
+ From the cross-genre games elements mentioned above, AtomCore introduce some concepts which latter implemented in classes in appropriate packages.
+....
+
+
+===== Entity
+
+
+===== Managers
+
+AtomCore introduce the concepts of Manager (then Helper, Worker, Actor later). What are they?
+
+
+Managers are useful objects (usually Singleton) to manage aspects of a game, such as Rendering,  Sounds, World, Assets, Networks, Effects, etc…
+
+
+Managers are born to help developer manage/ monitor/ manipulate every conner/ moment/ objects in the game code base and run-time activites.
+
+
+Manager is the concept of who have responsibities and power over others (as its children or employee in the real world), essentially it is a list of its children, and have basic opertions like add,remove to manage that list… You can also think about it as the Control of the MVC paradigm where it is the mediator between Model and View. In JME3, you see Manager every where such as AssetManager, StateManager as the wraper of underlying functions. So, event mixed up quite a lot concepts at once, Manager in Scripting is extremely useful and fullfill the missing piece of the picture we are painting for a while here.
+
+
+To clean the mist of confusion about mixed of concepts a little bit, there are some practical wisdoms about Manager implementation:
+
+
+....
+  Manager acts globally, handy: usually a Singleton, or really easy to reference in script
+  Manager wrap underlying details in intuitive way
+  Manager share common informations
+  Manager executions are frequently : like in an default update cycle
+  Manager have power over its children : its handle it children; in almost scenarios child has left its Manager's list come hollow (as null)
+....
+
+Entity related - Managers can be considered as the other piece in constrast with Entity, as it manage entity existing and activities. 
+
+
+Also note that Managers normally form a Tree, with Hierarchy or dependency as commonly seen in OOP.
+
+
+But, the Manager-Entity system is not forced to be in relationship with each other! If work as a flat array, the Manager system can be transform to a Component process as seen in COP. This open a door to integrated deeply with Component base solutions as describled below.
+
+
+
+===== Actor
+
+
+===== Task & Worker
+
+
+===== Helper
+
+
+===== Component base solution
+
+
+
+
+You can read about Component base solutions and architecture here:
+
+
+In AtomCore I sketch some interface of ES in which not care much about the implementation of the ES (pure data, smart bean, DB backed what ever…), open possiblities to intergrated ES libs in Atom framework.
+
+
+
+==== Common implementations
+
+....
+  Of course a framewok is almost meaningless if it just contain psuedo code or interfaces without inplementation. I also implemented some common and useful piecies of code which ready to use :p. 
+....
+
+
+===== Common Cycle
+
+The first thing should be mentioned, as essentital to the framework is root of the game activities: the Cycle - Ordered activities that repeat over and over!
+
+
+My basic form of game Cycle aka CommonCycle crafted to work well with AppState concept of JME3 and other existed Managers (StateManager, AssetManager, InputManager..).
+
+
+The Cycle consist 6 basis methods:
+
+
+.  init : Lazy init and be injected with its dependencies declaretion
+.  load : Load assets or underlying data (later than its dependencies) 
+.  config : reconfig if need, even in update
+.  start : trigger start a working routine of the object
+.  update
+.  end
+
+why 6? Why cycle? The customizable version of cycle? Introduce new cycles, queues and stuffs. read <<jme3/advanced/atom_framework/atomcore/cycle#,cycle>>
+
+
+
+==== Common scenarios
+
+Common scenarios that almost every game have, help you to startup easily. That mean the code is there in the library, you can also overide because its very extensible!
+
+
+*  Manage entities: add/remove/select 
+*  Composable logic: with condition, trigger
+*  Event messaging system (network ready): as inner / outter communicate media with eventbus and non blocking network
+*  Provide user functions and controls: As State, Control, Actors
+*  Game status persistent: Save/ Load/ Replay
+*  Routines: Interactive / non interactive as Cycle change to InteractiveMode or CinematicMode. Handle Tasks, Actions in good concurent way (multi threading, actor..).
+*  Easy UI making: as common ui below
+
+
+== Common scenarios Detailed
+
+
+=== Game related
+
+
+==== Managed entities
+
+The AtomCore offer (but not forced) you a way to manage “your entities (game objects) embeded to a scenegraph . This is the distinct point that made AtomCore entity difference with “other entity framework (component entity, pure data, …)
+
+
+Detail:
+
+
+
+==== Composable logic
+
+In AtomCore version 0.1, i've implementated my own Conditional checking and composing classes and functions to build up a composable logic system. That means compose a logic phrase out of 2 boolean values: true and false!
+
+
+This system later can be use as piece in Gameplay composing, piece of Decision tree, as Guard in Finite State Machine, as condition in selecting…
+
+
+In AtomCore 0.2, I made a change, consider big affect to the whole AtomCore I adapted to Guava's Function and Predicate. What's so intereting about Java's functional flavours? It provides more ways to compose logic, also more consise, readable, resuable if done right… Read more about Predicate:
+link:http://code.google.com/p/guava-libraries/wiki/FunctionalExplained#Predicates[http://code.google.com/p/guava-libraries/wiki/FunctionalExplained#Predicates]
+link:http://java.dzone.com/articles/google-guavas-predicates[http://java.dzone.com/articles/google-guavas-predicates]
+
+
+Detail:
+
+
+
+==== Event message system
+
+With eventbus 
+
+
+non blocking network
+
+
+
+==== Common state
+
+In turn, along with this pre defined cycle, some common states which ready to use
+
+
+*  LoadState : load / watch
+*  MenuState : select / option / ingame / exit
+*  InGameState : pause/ stop 
+
+
+==== Common Routines
+
+Handle Tasks, Actions in good concurent way (multi threading, actor..).
+
+
+
+===== Common Controls
+
+EntityControl 
+
+
+SpatialEditorControl 
+
+
+AtomCharacterControl
+
+
+AtomAnimationControl
+
+
+IKControl
+
+
+
+==== Common Actors
+
+
+==== Game status persistent
+
+
+===== Save
+
+
+===== Load
+
+
+===== Replay
+
+
+==== Common UIs
+
+Provide a easy way to make +++<abbr title="Graphical User Interface">GUI</abbr>+++ out of XML, bean, text, script… as seen in MetaWidget. Binding means input and data transaction ready.
+
+
+Some common game UI as FlashScreen, MainMenu, Options, Lobby, Credit…
+
+
+Advanced UI operation is on AtomGUI
+
+
+
+=== Application related
+
+
+==== Common Configs
+
+
+==== Common Services
+
+
+=== Packages
+
+
+==== sg.atom.core
+
+Core elements of the framework.
+
+
+*  annotations 	Annotations to setting up elements in java code. [Same in every packages!]
+*  assets 			Facilities to import / export assets from JME3 pipeline
+*  bean			Facilities to use Java bean in Atom context with mapping and binding.
+*  config			Facilities to use Configs in Atom, with the help of Common Configuration
+*  context			Bridge concepts help to bring entities from one enviroment to others crossed platforms.
+*  execution		Facilities for execution, with help of Common lang and Guava
+*  lifecycle		Concepts for game (and real time application) cycle
+*  monitor			Facilities to monitor your game and application
+*  timing			Concepts &amp; Facilities for real time application
+
+
+==== sg.atom.entity
+
+Concepts and Facilities to build up Game object. [Beta]
+
+
+
+==== sg.atom.fx
+
+Concepts and Facilities to create and manage animations and effects.
+
+
+*  anim			Concepts for animation
+*  automatic 		Automatic driven for animation
+*  constraint		Other way to declare relationship between entities and activities
+*  filters			Additions to JME3 filters
+*  functional		Functional flavours for effects
+*  particles 		Concepts to build bigger system from smaller part [Atom concepts]
+*  sprite			Concepts for cross dimensional elements
+*  timeline		Enhance of timming framework
+*  transition		Transition between stateful objects 
+*  tween			Object interpolations.
+
+
+==== sg.atom.gameplay
+
+Concepts and facilities for games (cross-genre)
+
+
+*  action			Concepts and interfaces for action in games
+*  controls		Additional to JME3 character controls
+*  league			Leagues  group and tournament of players
+*  managers		Manager of leagues  group and tournament of players
+*  player			Player and their data
+*  replay			To record the game activities
+*  score			To recored the game results
+
+
+==== sg.atom.logic
+
+Basic block for building game from a programming language via formal system.
+
+
+
+==== sg.atom.net
+
+Concepts and interfaces for connectivity and communication via networks
+
+
+
+==== sg.atom.stage
+
+Concepts and facilities for cinematography like games
+
+
+*  actor			Bridge from entities to actor framework	
+*  cine			Sostiphicate cinematic framework for complex video games
+*  helpers			“Inplace controls which know about Stage. Bridge from JME3 Controls concepts
+*  input			Sostiphicate high level input system use for develop and test game
+*  select			Facilities for selecting (from input) an on screen spatial or entities
+*  sound			Additional facilities to JME3 sound system
+*  sync			Additional facilities to syncing between multi thread progress
+
+
+==== sg.atom.state
+
+Additional for JME3 app state (bridge between to systems) and some common states for a common games
+
+
+
+==== sg.atom.ui
+
+General +++<abbr title="Graphical User Interface">GUI</abbr>+++ for user interaction and styling in hierachy (non-strict) elements
+
+
+
+==== sg.atom.utils
+
+Collections of userful utilities and datastructures, algorimths here and there. 
+
+
+
+
+
+
+==== sg.atom.world
+
+Concepts and interfaces to build and manage the game world and enviroment
+
+
+*  gen				Generate the world from data
+*  geometry		Maths for geometries
+*  lod				Level of detail framework provides a lot of methods to optimize scene and geometry. 
+*  material		Additional to JME3 material system
+*  physics			Additional to JME3 physic system
+*  rendering		Additional to JME3 render system
+*  terrain			Additional to JME3 terrain system
+*  visibility		Additional to JME3 cull and partition system
+
+
+== Documentation
+
+
+== Troubleshooting, gotchas & Best practices
+
+
+== Contributions

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

@@ -0,0 +1,18 @@
+
+Actor is
+
+
+AtomActor is
+
+
+
+== Concepts
+
+
+=== Act
+
+
+=== React
+
+
+=== Interact

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

@@ -0,0 +1,538 @@
+
+
+== Algorimths for games
+
+Single (or serveral) objective algorimths useful for games.
+
+
+link:http://en.wikipedia.org/wiki/Algorithm[http://en.wikipedia.org/wiki/Algorithm]
+
+
+link:http://en.wikipedia.org/wiki/Linear_programming[http://en.wikipedia.org/wiki/Linear_programming]
+
+
+Algorithm is a step-by-step procedure for calculations. An algorithm is an effective method expressed as a finite list[1] of well-defined instructions[2] for calculating a function.[3] Starting from an initial state and initial input (perhaps empty),[4] the instructions describe a computation that, when executed, proceeds through a finite[5] number of well-defined successive states, eventually producing “output[6] and terminating at a final ending state. The transition from one state to the next is not necessarily deterministic; some algorithms, known as randomized algorithms, incorporate random input.[7]
+
+
+Linear programming (LP, or linear optimization) is a method to achieve the best outcome (such as maximum profit or lowest cost) in a mathematical model whose requirements are represented by linear relationships. More formally, linear programming is a technique for the optimization of a linear objective function, subject to linear equality and linear inequality constraints. Its feasible region is a convex polyhedron, which is a set defined as the intersection of finitely many half spaces, each of which is defined by a linear inequality. Its objective function is a real-valued affine function defined on this polyhedron. A linear programming algorithm finds a point in the polyhedron where this function has the smallest (or largest) value if such a point exists.
+
+
+
+=== Why use this ... for games?
+
+This package provides algorithms common in game developments. More to come but first let's take a look of those problems it trying to solve to distingish the objective and goals of this package compare to collection and others.
+
+
+
+==== It's not another Collection (DataStructure) or Pattern package!
+
+Sort, concurrent, packing, data compressing is also partial relate to its processing method (that's algorithm) but first, they are provided as the core of the programming language, second we want to care more about the high level of abstraction, not the details. It use “interface of structure for its explaination and progress.
+
+
+Also, pattern is the term refered to a popular method in software developmenet. Pattern is also in higher level of abstraction compare to algorimths. So consider pattern is the law and algorimth is the effective way of making the job work effectively obey that law.
+
+
+Algorithms involve logic, a lot of them. But it higher level than logic. And of course algorithms need math (some physics, philosophy also) to be smart!
+
+
+Algorithms are used heavily in AI. But this package only provide pure algorithms which can be used also outside of AI topics.
+
+
+That's said:
+
+
+*  Datastructure, Pattern, Logic and AI are supported elsewhere!
+**  Algorimths depends in Pattern, Logic, Interface of Structure.
+
+
+==== Each algorithm has a goal (or several) to accomplish!
+
+Developer want to use the algorithm they know to solve one or more goals (problem, requirement, aspect, situation, … what ever you call it). The algorithms provided here are the bricks for you to use and reuse, for different purposes. And you may notice the package also be arranged into purposes instead of implementations - techniques or another structure. That's explained the reason!
+
+
+
+==== For games?
+
+Yes, not all of the problems we know are solved by this library…??? You've already know. It not even sotiphicated like the alternatives below but they are extremely useful for average programmers; especially game programmer, who, usually focus in the fun side (Am I right? :) )
+
+
+The library try to provide useful algorithms (best practices and wisdoms) enough for a wide range of usecases and also used in Atom framework its self. The algorimths them self may use another algorimths to solve sub-problems. Of course, it also come with examples and a lot of applications & suggestion, which its the algorithms use for you to quickly and smartly solve your own problem thank to it.
+Support algorithms by purposes
+
+
+....
+ 1. Allocation: solve problems about resources.
+       1. Allocate resources efficiently on demand and sastify requirements:
+             1. in an amount of time (interval, arrangement, progess, budget)
+             2. with specific capacities of the network and memory (flow, route, budget)
+             3. with dependencies (order)
+             4. skip or retry if unsuccess (fault-tolerant)
+             5. cache
+       2. Skip resources that fault-tolerant: ( aka Reject)
+             1. Not affect its dependencies, or skip those dependant
+             2. Preseved the continuous, so the flow still smooth
+       3. Release resources ( aka Remove)
+             1. Determiate which resource are no more needed
+             2. Help the gabbage collector, cache to remove it
+       4. Update resources
+             1. Only what that need to be update
+             2. Deffered till the update process not abuse the other pioritied operations
+ 2. Balance: find a division, equallity equilibrium between inputs of forces (presure).
+       1. Exchange: when force interact
+       2. Equilibrium: when force include, conccure together and zero total
+ 3. Energy : more than just physics simulation, its applied physics-math based methods
+       1. Static:
+       2. Dynamic:
+       3. Potential: 
+       4. Tension:
+ 4. Constraint: find a solution that sastify a list of constraints.
+       1. Search for sollution in avaiable space (travel)
+       2. Generate a sollution base in template
+ 5. Interval: various problems related to intervals (values a duration of time).
+       1. Progress monitoring
+       2. Schedule jobs
+ 6. Optimization: to optimize toward a goal
+       1. Maximize - minimize:
+       2. Resolution: Find a solution upon a known solution (aka neirghboor search)
+       3. Boost: wisdoms  to make higher performance and more efficient algorithms if not saturated (without resolution)
+             1. Reactive
+             2. Adaptive
+             3. Fractal
+ 7. Relate: solve problems between things relate to other (Very close to abstract aglebra):
+       1. Reconfiguration: if one change, others react
+       2. Coupling: link-relink-relax link-remove link between two or a group by cateria (aka clustering)
+       3. Dependency: direct/ indirect depend on other and how to isolate
+       4. Order: study of ordering, very similar to sorting wisdoms but in higher level.
+ 8. Score: Study the "number","amount" (aka quantity) of things; summarize and judge (aka quality). Wisdoms about: Measuring, scale, approximation, coloring or the alike.
+       1. Budget:
+       2. Audit: (aka Accounting)
+       3. Cardinality:
+ 9. Travel: Study the step by step "move" between unit of things. This is a fundamental and essential spirit of algorithms.
+       1. Search: Study the exploring in space.
+       2. Trace: Study the affection (footprint, operations, cost.. ) the algorithms left each step
+       3. Track:  Study the  route  (path, track, flow,...)  the algorithms  pass.
+10.  Generation: good practises in making new things
+       1. Template is the resource of generation
+       2. Production is the progress of creating new things
+....
+
+
+== Concepts
+
+First of all this package has some degree similar to JScience and Opt4J… I can't denied I had used them intensively to know what is good and what is not. About the similarity between Ptolemy and Atom, even the two take different approaches and implementation, you can read from the Atom framework introduction.
+
+
+Algorimths in computing, programming and game programming has grown, based in knowledges and wisdoms from a lot of other sciences: math, physics, philosophy, chemistry, biology… etc. Here and there the concepts are familiar with developer because they've taught in schools. Some may require extra knowledge from mathematics and physics per se… But you know google can have any way.
+
+
+Here is the part where the concepts which used in algorithms in Atom framework which you can reference and research futher. Almost every part you can also google about them or try to find it in jscience +++<abbr title="Application Programming Interface">API</abbr>+++ javadoc:
+
+
+link:http://jscience.org/api/index.html[http://jscience.org/api/index.html]
+
+
+link:http://jscience.org/experimental/javadoc/[http://jscience.org/experimental/javadoc/]
+
+
+
+=== From Mathematics
+
+
+==== Algebra
+
+
+==== Topo & Graph
+
+
+=== From Physics
+
+
+==== Common
+
+
+==== Kinematic
+
+
+=== From computing techs
+
+
+=== Saturation of algorithms:
+
+You may notice that if there is a “pattern or “algorimth to optimize a progress. Can we use them repeatly until processing time toward minimum or even zero????
+
+
+This sounds totally untrue and also ridiculous but an interesting captious way of thinking. 
+
+
+link:http://algs4.cs.princeton.edu/66intractability/[http://algs4.cs.princeton.edu/66intractability/]
+
+
+link:http://en.wikipedia.org/wiki/Time_hierarchy_theorem[http://en.wikipedia.org/wiki/Time_hierarchy_theorem]
+
+
+link:http://www.npr.org/blogs/13.7/2011/09/19/140599268/minds-and-machines-the-limits-of-turing-complete-machines[http://www.npr.org/blogs/13.7/2011/09/19/140599268/minds-and-machines-the-limits-of-turing-complete-machines]
+
+
+link:http://en.wikipedia.org/wiki/Turing_machine#Computational_complexity_theory[http://en.wikipedia.org/wiki/Turing_machine#Computational_complexity_theory]
+
+
+Here i used the term the *saturation of algorithms* to describle the problem from overview.
+
+
+Let say the algorithm A needs B to compute, and than B needs A to compute. The Recursion will be forever in the turing machine such as our computer, until we out of memory or can even cause a crash in some programming language and computer-small scale ones (pc,console…). In real-life, it's hardly useful for game developing. 
+
+
+For example: 
+
+
+In Allocation package, we need to compute the dependencies between resources, si call Dependency package. In computing dependency, we need resource so we call allocation package… This loop is actually fine but its will run forever if there is no saturation point or the end point of the recursion calls. 
+
+
+So in AtomAA, there is a detection of Recursion and cyclic dependency that can break-out early from the infinite loops. Also if Dependency package call, it tell Allocation not to call it again in the amount of time. Allocation then will chose another path of computing by just allocate directly. This not gaurantee to prevent the problem but ease out the percentage you fall into a dead trap. It work pretty much like concurrent contention resolving in by synchronization in Java. 
+
+
+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:*…
+
+
+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.
+
+
+
+== Implementation details
+
+*[JavaAA]*
+
+
+
+=== Allocation
+
+solve problems about resources.
+
+
+....
+Allocate resources efficiently on demand and sastify requirements:
+  in an amount of time (interval, arrangement, progess, budget)
+  with specific capacities of the network and memory (flow, route, budget)
+  with dependencies (order)
+  skip or retry if unsuccess (fault-tolerant)
+  cache
+Skip resources that fault-tolerant: ( aka Reject)
+  Not affect its dependencies, or skip those dependant
+  Preseved the continuous, so the flow still smooth
+Release resources ( aka Remove)
+  Determiate which resource are no more needed
+  Help the gabbage collector, cache to remove it
+Update resources
+  Only what that need to be update
+  Deffered till the update process not abuse the other pioritied operations
+....
+
+
+=== Balance:
+
+....
+find a division, distribution for equality, find equilibrium between inputs of forces (presure).
+ Exchange: when force interact
+ Equilibrium: when force include, concur together and zero total
+ 
+....
+
+higher wisdoms than equality and difference. Its the progress of making two or more things equal by exchanging one by one (local optimal or greedy). It's also a study of distribution to find equilibrium between inputs of forces. This problem araise a lot in classical game theory and later game developing. 
+
+
+Read: 
+link:http://en.wikipedia.org/wiki/Game_theory[http://en.wikipedia.org/wiki/Game_theory]
+
+
+link:http://en.wikipedia.org/wiki/Solution_concept[http://en.wikipedia.org/wiki/Solution_concept]
+
+
+link:http://en.wikipedia.org/wiki/Nash_equilibrium[http://en.wikipedia.org/wiki/Nash_equilibrium]
+
+
+link:http://en.wikipedia.org/wiki/Ultimatum_game[http://en.wikipedia.org/wiki/Ultimatum_game]
+
+
+
+=== Energy :
+
+....
+more than just physics simulation, its applied physics-math based methods
+  Static:
+  Dynamic:
+  Potential: 
+  Tension:
+....
+
+
+=== Constraint:
+
+find a solution that sastify a list of constraints.
+
+
+....
+Search for sollution in avaiable space (travel)
+Generate a sollution base in template
+  
+....
+
+
+=== Interval:
+
+various problems related to intervals (values a duration of time).
+ Progress monitoring
+ Schedule jobs
+
+
+
+=== Optimization:
+
+to optimize toward a goal
+
+
+....
+ Maximize - minimize:
+ Resolution: Find a solution upon a known solution (aka neirghboor search)
+ Boost: wisdoms  to make higher performance and more efficient algorithms if not saturated (without resolution)
+   Reactive
+   Adaptive
+   Fractal
+ Evolutionary: 
+....
+
+
+=== Relate:
+
+ solve problems between things relate to other (Very close to abstract aglebra):
+
+
+....
+ Reconfiguration: if one change, others react
+ Coupling: link-relink-relax link-remove link between two or a group by cateria (aka clustering)
+ Dependency: direct/ indirect depend on other and how to isolate
+ Order: study of ordering, very similar to sorting wisdoms but in higher level.
+....
+
+The relationship between things cause complex problems, this package try to solve a subset of problems which is useful in programming and gamedev in general. Relation is very abstract, but some of  “relationship problems are well-defined like:
+
+
+*  the cause of declaration of relationships 
+*  the dependency between two subject
+*  the direction, order of relation or force
+*  the configuration need to the relationship
+
+*Dependency*: If one object “declare relationship to another, aka one-direction link:
+*Coupling*: If two objects “declare relationship between each other, aka bi-direction link:
+
+
+*  [Real-life] Imagine the marriage law when two get married :) 
+*  [Computing] The dependency between packages, modules, operations, tasks.
+*  [JavaAA] 
+**  The links can be create or not? 
+***  to prevent NullPointException if you invoke an empty link.
+***  to prevent IllegalException because of tabboo
+***  full satifaction conditions?
+
+**  What need for a link to be create? 
+***  load needed assets, classes, modules.. - like what osgi and maven does
+***  the first-attempt configuration in the two subjects.
+
+
+
+*Reconfiguration*: If two objet “change the relationship and the affections.
+
+
+*  [Real-life] Imagine a devote, and the fate of the property and children
+*  [Computing] Reconfiguration cause computation in the said domain and cause a chains of reaction in the network. The reconfiguration can cause “bigger affection than the first time config, but how to decrease the cost?
+*  [JavaAA] 
+**  Is there anything i can save?
+***  what is still valid and update just the delta?
+***  what is properly unchanged and really can not be changed?
+***  what will be abandond after reconfig?
+***  can the reconfig progress delay or divide-to-conquer?
+
+**  This also envolve in general LOD (LevelOfDetail) problems, which mainly focus in reconfig after changes. Divide-to-conquer is the main wisdom of this class of problems.
+
+
+*Order*: directions, or the order of travelling when bunch of objects are related.
+
+
+*  [Real-life] I want to travel in a city by roads. I have to know the map.
+*  [Computing] Graph problems and how to change the direction of processing
+*  [JavaAA] 
+**  Sort in graphs &amp; Order of Nodes
+**  Direction of Track
+**  Order of Intervals (conccurent progresses)
+
+
+
+=== Score:
+
+Study the “number,“amount (aka quantity) of things; summarize and judge (aka quality). Wisdoms about: Measuring, scale, approximation, coloring or the alike.
+
+
+....
+ Budget:
+ Audit: (aka Accounting)
+ Cardinality:
+ 
+....
+
+This package support the invoke of functions and actions for measurement in single step or a chain of steps. Also it provide the remain of power within a Budget. After serveral of steps, it can invoke audit for examine the progress. For doing this, it has to know detail about Unit by understand Cardinality in the context. 
+
+
+This package depend in Commons Math and JScience for useful functions.
+
+
+
+=== Travel:
+
+Study the step by step “move between unit of things. This is a fundamental and essential spirit of algorithms. <<jme3/advanced/atom_framework/atomcore/algorithms#algorimths_for_games,Read back algorithm definition above>>
+
+
+....
+ Search: Study the exploring in space.
+ Trace: Study the affection (footprint, operations, cost.. ) the algorithms left each step
+ Track:  Study the  route  (path, track, flow,...)  the algorithms  pass.
+ 
+....
+
+Travel depend in relate. It Explores bunch of things that relate to each others in a space (Data space, time space). The process known as Search. Doing Search, it left Traces. Flowing trace in each step, one can see a Track or a Flow of the progress.
+
+
+This package support: datastructure-agnostic search, traces and tracks (beside of those already supported in Java, Guava…)
+
+
+Search:  
+DFS, BFS, Traveler 
+
+
+Trace: 
+Visit, Footprint (mark), Cost
+
+
+Track: 
+ForwardTrack, BackwardTrack, Flow (TotalCostTrack-SingleStepCostTrack), FlowCapacity
+
+
+
+=== Generation:
+
+ good practises in making new things
+
+
+....
+ Template is the resource of generation
+ Production is the progress of creating new things
+....
+
+A collections of wisdoms explain what/why/how to generate new things smart and efficiently.
+
+
+*  [Math] A function from one domain to another domain. 
+**  link:http://en.wikipedia.org/wiki/Function_%28mathematics%29[http://en.wikipedia.org/wiki/Function_%28mathematics%29]
+
+*  [Physics] Energy from one form to another. 
+**  link:http://en.wikipedia.org/wiki/Conservation_of_energy[http://en.wikipedia.org/wiki/Conservation_of_energy]
+
+*  [Language] Translate sematic from one to another language need a dictionary. 
+**  link:http://en.wikipedia.org/wiki/Semantic_similarity[http://en.wikipedia.org/wiki/Semantic_similarity]
+
+*  [Art] Nothing new, just a cover. 
+**  link:http://www.brainyquote.com/quotes/quotes/p/pablopicas380469.html[http://www.brainyquote.com/quotes/quotes/p/pablopicas380469.html]
+**  link:http://idioms.thefreedictionary.com/There+is+nothing+new+under+the+sun[http://idioms.thefreedictionary.com/There+is+nothing+new+under+the+sun]
+**  link:http://thephilthyway.files.wordpress.com/2012/09/boycottapple.png?w=549&h=279[http://thephilthyway.files.wordpress.com/2012/09/boycottapple.png?w=549&amp;h=279]
+
+*  [Computing] Template is a good abstraction of algorimths. 
+**  link:http://en.wikipedia.org/wiki/Generic_programming[http://en.wikipedia.org/wiki/Generic_programming]
+
+*  [Programming] DRY , data-driven and open source. 
+**  link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[http://en.wikipedia.org/wiki/Don%27t_repeat_yourself]
+**  link:http://en.wikipedia.org/wiki/Open_source[http://en.wikipedia.org/wiki/Open_source]
+**  link:http://en.wikipedia.org/wiki/Data-driven_programming[http://en.wikipedia.org/wiki/Data-driven_programming]
+
+*  [New techs &amp; trends] Topology and well defined network actually a virtue. 
+**  link:http://en.wikipedia.org/wiki/Distributed_computing[http://en.wikipedia.org/wiki/Distributed_computing] 
+**  link:http://storm.incubator.apache.org/[http://storm.incubator.apache.org/]
+
+
+
+=== Limitations and futures
+
+Only simple forms. But External libs can be hooked!
+
+
+Usage of interface from sg.atom.world.physics package, should be all in sg.atom.utils only!
+
+
+Lack of unit tests. But in the future
+
+
+Lack of better documentation and education. Here you are, improve it your self.
+
+
+
+== Applications
+
+
+=== In Atom framework
+
+Used in Asset/Task packages
+
+
+
+=== Others
+
+This small library can be used in a wide range of applications especially games and simulations. 
+
+
+
+
+
+link:http://en.wikipedia.org/wiki/Algorithmic_game_theory[http://en.wikipedia.org/wiki/Algorithmic_game_theory]
+
+
+link:http://en.wikipedia.org/wiki/LP-type_problem[http://en.wikipedia.org/wiki/LP-type_problem]
+
+
+link:http://en.wikipedia.org/wiki/Multi-agent_systems[http://en.wikipedia.org/wiki/Multi-agent_systems]
+
+
+link:http://en.wikipedia.org/wiki/Auction_Theory[http://en.wikipedia.org/wiki/Auction_Theory]
+
+
+
+== Alternatives
+
+For scientific wisdom in Java:
+
+
+link:http://jscience.org/[http://jscience.org/]
+
+
+For full-ledged multi objective meta heristic algorithms, try:
+
+
+link:http://www.joptimizer.com[http://www.joptimizer.com]
+
+
+link:http://opt4j.sourceforge.net/[http://opt4j.sourceforge.net/]
+
+
+link:http://jmetal.sourceforge.net/[http://jmetal.sourceforge.net/]
+
+
+Constraint programming and solver:
+
+
+Choco
+
+
+JACK
+
+
+JaCop
+

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

@@ -0,0 +1,40 @@
+
+
+== Atom framework's Beans
+
+
+=== Technologies
+
+Bean is nothing new in Java, actually is … (a long story) plain old :)
+What Atom'sBeans try to do is similar to EJB without its complexility. Because we have to use it in real-time enviroment, we have to make its fast and have high through put performance.
+
+
+*  Bean binding : reactive binding with generated functions like 2-way mapping below
+*  Bean mapping / morphing : bytecode generation (or reflection) for mapping and interpolating, remote syncing 
+*  Bean modelling : code generation directly from java-java, java-xml, java-html
+*  Bean generation : bytecode generation with conventions, specifications, configurations to make Java's Object's bytecode cross platform as data
+*  Distributed bean: distributed bean with RPC and syncing
+
+The most different between this bean frameworks and others is it stand in J2SE specification and make bean related job really easy as it should! See to believe.
+
+
+
+=== Components
+
+
+=== AtomBean
+
+
+=== Bean binding
+
+
+=== Bean mapping / morphing
+
+
+=== Bean modeling
+
+
+=== Bean generation
+
+
+=== Distributed Bean

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

@@ -0,0 +1,3 @@
+
+
+== Atom Cinematic

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

@@ -0,0 +1,52 @@
+
+
+== Atom Configurations
+
+Atom Configurations provide facilities for do configurations and profiles for enviroments, Games of course instead of just normal Java applications.
+
+
+
+=== The past
+
+First let's take a look into the past of years and see how Java developers do configurations for their applications: 
+
+
+*  The config files for application in desktop enviroments may loaded from user's home, or the app's folder. The config files can be plain text, XML, JSON, binary or something else.
+*  The config can also be received from external sources like from network services, database. The protocol for them can be object base (POJO), relational structure based (resultset) or else …
+*  The config can also be intelligently procedure based in the stats and infos of the device or deployed enviroment…
+
+So there is not a single way to do configurations. Is there an unified way now?
+The answer is still NO. Configurations is the aspect of gamedev SHOULD be kept flexible the most. Tricks and smart stuffs can involve in this progress a lot: optimizations, per device & per user configuration, policies… In another hand, it keep you busy with tricky parts and complexibilities of underlying datastructure and extra progress.
+
+
+Some other libraries and game engine tend to hide the detail from developer and provide a premade solutions for configurations in supported enviroment. 
+
+
+Ex: LibGDX with Prefs, Unity with Metadata, XNA with Properties…
+
+
+The more configurations apart from Data and Code, the more it getting complex. In the other hand, getting closer, it mixed and tangled with Data and Code. So how can we make it the right way?
+
+
+
+=== The solutions
+
+The Solution is actually very practical as it should. It's the corporation of existed techniques but with a fine-tuned and industrial approaches. The “Fine tuning are predefined or customized by the user them self (if they know how to do it). Isn't it what is configurations is all about. Think about a ridiculous control panel which have only one button, and the other complex and also not very useful with 300 of them… This framework is your control panel, tailored by you! What it help:
+
+
+.  There are “fine-tuned configurations for enviroments , devices, users, or aspects… and custom configurations for arbitrary scope and context.
+.  Abstract out the data structure of configurations and its lower level of persist, load and communications.
+.  Revolution in the publish, deloy enviroment and progress: to make the configuration actually is data (and code…), not something else.
+
+
+=== Technologies
+
+.  AtomEx's Universe provide a repository of configuration profiles. Concepts and mechanisms of Atom's Universe is the similar to Maven repository. So Java dev can use Maven or Gradle to include them at development time (or even runtime). In runtime, an IOC mechanism is provide for configurations initialization similar to Spring system.
+.  Apache Commons & Archaius to abstract out the data structure of configurations. Under them are Utils that consider appliance of configurations as watchable Tasks.
+.  Gradle and Go is employed in the deploy progress make it very flexible and watchable. Configuration publishing is supported by tailored +++<abbr title="Graphical User Interface">GUI</abbr>+++ Editors in JMP. Generic configuration editors for Text, Properties, XML, JSON… are also provided.
+
+
+== Toolset
+
+
+== Documentation

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

@@ -0,0 +1,198 @@
+
+
+== Well defined Cycles
+
+Cycle are ordered activities which repeat over and over during the entire application life time. It's usually referred as game loop. 
+
+
+If you see a cycle as a list (ordered collection) of actions that the application does one at a time. You will see the application Iterate over them. In the opposite view (or in the action body), a traveller (usually data) seen it drag from one to the next one, so call pull to next step.
+
+
+As Atom also support reactive programming, it's essential that developer should understand clearly what is the benefit of program with this direction or other. To get (Between) BEST OF BOTH WORLD! 
+
+
+
+=== Why 6?
+
+Game programmer usually stick with 3 steps execution
+
+
+.  init 
+.  update
+.  destroy
+
+Instead of that, Atom use 6 steps execution cycle:
+
+
+.  init
+.  start
+.  load
+.  config
+.  update
+.  finish
+
+These 6, I carefully learnt from other “good module and component framework I 've use: Wicket, OSGi,Spring…they have different steps number! 
+
+
+link:http://wicketguide.comsysto.com/guide/chapter6.html#chapter6_1[http://wicketguide.comsysto.com/guide/chapter6.html#chapter6_1]
+
+
+link:http://en.wikipedia.org/wiki/OSGi#Life-cycle[http://en.wikipedia.org/wiki/OSGi#Life-cycle]
+
+
+link:http://www.tutorialspoint.com/spring/spring_bean_life_cycle.htm[http://www.tutorialspoint.com/spring/spring_bean_life_cycle.htm]
+
+
+The reason of these 6 step routine compare to 2,3,4,5.. or any other division is to support lazy loading, heavy task, gabage collection wise, much more…
+
+
+So we usually have these 3 main methods:
+
+
+....
+init , start , end
+....
+
+For a real-time game, we need 2 more:
+
+
+....
+load, update
+ 
+....
+
+“Config method is kind of a replicate of “init or “load, or confusion of these two, even can be done in “update somehow but in fact, it's worth to be separated. The config step will help you gain a lot in the way to extend the frameworks or to adapt/scale  your game to smaller or bigger usecase, anyway 6 “is not too much but enough !
+
+
+Anyway this is a common cycle and compromise between ICycle who join the Atom conversations; that's hook in methods (classic style isn't it?). Beside of that, you can define your own routines through safe tasks and channels which provided by AtomMain. Though this tunnels, all your operations are guarantee to be not conflict in concurrent term with any other jobs of Managers, actors or helpers. So the Data is for you until you end the tasks (or be shut by forced because timeout for ex)!!
+
+
+
+=== Pull or push?
+
+As said in the analysis about JME3's patterns, especially rendering and update loop, it's pull and push at the same time. Confused? Yes it's… Why is so confused?
+
+
+Java developers are “toooo familiar with MVC architecture that bring to us by Swing and all classic sun solutions. That's why we find them in every programming books and every beginner's articles, especially if you develops game in desktop, (obviously in swing also). OpenGL and LWJGL also start as window based solution. So that we get “used to it… Latter, a lot of web frameworks also make tanged mess of push & pull concepts?
+
+
+Swing-MVC concepts are embeded in a event-driven enviroment… and it's actually pull.
+
+
+Real-time application can be event-driven or not. As my exprience, apply this Swing-MVC to real-time application not usually help greatly but sounds very confused and blury. It can help if you too familiar with it anyway, but be careful or you break the MVC contracts easily and make it not useful. You can blindy apply it without concerning of consequence, but that don’t make any sense.
+
+
+The solid and only reason to say JME3 is pull and push, and why we still has to stop once for a while because of OpenGL via LWJGL is still monotholic! Not the GPU processing or GPU-CPU data exchange. So we still have to stop at the renderer's door, knock and wait until its done, then go to next step? Umh not quite. 
+
+
+But to do this, we have to not depend in the update() and render() methods to get to total freedom. 
+
+
+
+==== Concurrent / Parallel world
+
+Welcome to the parallel world which some time the well-defined cycle not even exist.
+
+
+But the routine or the flow does exist indeed!
+
+
+Just look at how your “data or “signal actually run through your systems, though “node and “stages as a network of roads & cars. This actually a well-study area known as data flow analysis. In a perspective, data seem to be “pushed from sources to targets. Some may also view its as data are “requested by some nodes and “pulled by those nodes.
+
+
+link:https://github.com/Netflix/RxJava/wiki[https://github.com/Netflix/RxJava/wiki]
+
+
+
+==== What is the new routines options?
+
+Even if “Cycle- which we used to known is just a conceptual view of points, my solution for this problem is to declare several new kinds of well-defined “Cycle :
+
+
+.  Push cycle 
+.  Pull cycle 
+.  Non-cycle
+
+… because defining routines in Atom is not only free but also helps in a lot of situations like when you interact with GUIs, networks or webs.
+
+
+
+===== Pull cycle
+
+To connect to Swing MVC (also a pull cycle) with events, you can wrap them in Actors and let events send as messages between actors. The Swing actor in the EDT act as the brigde here. 
+
+
+
+===== Push cycle
+
+As in functional reactive programming and flow based programming, functions (small piece of jobs) are flow with their data. A flow is not a well defined cycle but a routine and can be monitored.
+
+
+
+===== Non-cycle
+
+A serial of Tasks can also form atribinary routines ( non-cycle) and be coordinated together via Data they exchange. 
+
+
+
+
+
+
+== Customable cycles
+
+
+==== Customable routines
+
+Via tasks and workers, you can atribinary make your own cycle that do anything around and later participate in the rendering stage and JME logic stage (if they want).
+
+
+This freedom of doing things (in parallel if you want) is thanks to lock-free concurrent algorimths and data structure that Atom use. In other hand, the synchonizing problem is under research!
+
+
+Read: <<jme3/advanced/atom_framework/atomcore/concurrent#, AtomPar>>
+
+
+
+==== Customable (rendering) bucket
+
+Bucket is a way to layered your rendering queue into layers or separate them into different categories (aka buckets) to handle differently.
+
+
+With a composable comperator, a sub-list from a list, or a sub-tree from a tree, even a sub-graph from a entire scene graph can be extracted, or the whole collection can be sorted arcordingly. Custom bucket in Atom framework is implemented in AtomLight package to extend JME3 rendering pipeline. 
+
+
+Note that a custom bucket is not very efficient! Even though if you enable a setting, Atom will take care of its render order and the update will be “IO wise with special indexing structure call B-Tree. If you use it without cautions it can require a lot of memory and make your rendering suffer. 
+
+
+
+== Cycle & Scale
+
+You can see there is a trend for networks call non blocking IO, which Node.js is the first most and remarkable success. In that world, there is actually not a wellform cycle or turn at all. Because if there is a Queue or a lock, a insist port holder or an strict order (like a cycle), it can not scale at all!!
+
+
+In fact the atribinary networks and async data signals have a lot more problems than we can possible imagine. Not everything can be fast and precise…Some parts (services) may be slow by intend, some parts cause errors frequently. 
+
+
+The fault torrent architecture of AtomEx make sure some sercurity and transactional problems are shielded. AtomDust in another hand focus in highly loose mobile devices and atribinay short range connections. Those carefully design systems for usecases actually make Atom suitable even without a real Cycle.
+
+
+
+
+
+
+== Technical reviews
+
+
+==== Cycle (or ring)
+
+
+==== Cicular (or ring) buffer
+
+Ring buffer is fast way to make concurrent real time data streaming…
+
+
+link:http://mechanitis.blogspot.com/2011/06/dissecting-disruptor-whats-so-special.html[http://mechanitis.blogspot.com/2011/06/dissecting-disruptor-whats-so-special.html]
+
+
+
+==== Is there a real cycle? or just a lot of streams

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

@@ -0,0 +1,58 @@
+
+
+== AtomES - Entity Ecosystem
+
+*Real Object Oriented Programming Eco system.*
+
+
+
+=== Innovitation
+
+*OOP is not Class-based!*
+
+
+Read: link:http://qi4j.org/[http://qi4j.org/]
+
+
+*Entity System is a good choice to start your game!*
+
+
+Read: link:http://hub.jmonkeyengine.org/forum/topic/entity-system-topic-united/[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]
+
+
+
+
+
+
+=== Features
+
+*  Usable implementation which let Entity live in high concurrent distributed (over network) enviroment.
+*  A generic +++<abbr title="Application Programming Interface">API</abbr>+++ to implement a framework for your self
+*  Adapters for other ES frameworks to adapt to AtomES eco-system.
+
+
+== Technical review
+
+
+== Programming aspects
+
+
+=== Reusable
+
+
+=== Event communication
+
+
+=== Concurrent
+
+
+=== Workload and dataflows
+
+
+=== Java Expansion
+
+
+== Documentation

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

@@ -0,0 +1,3 @@
+
+
+== AtomCore 's Events

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

@@ -0,0 +1,109 @@
+
+
+== Atom Core Network framework
+
+*Atom Core Network framework is for networked game developing in Java. Powered by JME3, SpiderMonkey, MirrorMonkey and Netty.*
+
+
+
+=== Introduction
+
+To make developing networked game (multiplayer, social, even MMO..) in JME3 much more easier! With Java, with tools, with monitors!
+
+
+This module depends in JME3, SpiderMonkey, MirrorMonkey and Netty. It has all the features that libries it depends on have with ultimate extra power!!
+
+
+You can include Optional modules like Kryo (Kryonet), ProtocolBuffer, Zay-ES which is official extensions for various of usecaces.
+
+
+
+=== Features
+
+
+=== Concepts & Papers
+
+
+
+
+*  Annotations: @Data, @Event, @Sync
+*  Interfaces: Hanler, Fiber, Filter
+*  Ultilities: NetworkType, NetworkService, NetworkBus
+*  Configurations: zero, override via XML, Groovy
+
+
+=== Quick look
+
+
+==== A simple network application
+
+[source,java]
+----
+class Client implement NetworkService{
+     DObject dobj;
+
+     void update(float tpf){
+         network.mirror(dobj);
+     }
+
+     public void response(NetworkService service){
+         dobj.mirror(service);
+    }
+}
+----
+[source,java]
+----
+class Server implement NetworkService{
+     DObject dobj;
+
+     void update(float tpf){
+          dobj.change()
+          network.in(client1,client2).mirror(dobj)
+    }
+
+     public void response(NetworkService service){
+         dobj.mirror(service);
+    }
+}
+----
+
+=== Under the curtain
+
+
+==== Dependencies
+
+
+==== NetworkType
+
+
+==== NetworkService
+
+
+==== NetworkBus
+
+
+== Examples
+
+Some examples 
+
+
+
+== Documentation
+
+
+=== Basic games networking
+
+link:http://gafferongames.com/networking-for-game-programmers/[http://gafferongames.com/networking-for-game-programmers/]
+
+
+link:https://developer.valvesoftware.com/wiki/Source_Multiplayer_Networking[https://developer.valvesoftware.com/wiki/Source_Multiplayer_Networking]
+
+
+
+=== Programming
+
+
+=== Workflows
+
+
+==== Tools

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

@@ -0,0 +1,30 @@
+
+
+== World.Spatial package
+
+Scenegraph
+
+
+SceneGraphUtils
+
+
+Spatial Scheduler
+
+
+Spatial Relation
+
+
+Spatial Proxy
+
+
+Spatial hash
+
+
+Spatial cache
+
+
+TransformUtils
+
+
+TransformAligner
+

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

@@ -0,0 +1,33 @@
+
+
+== World
+
+
+=== Enviroment
+
+
+=== Geometry
+
+
+=== Generation
+
+
+=== Level of detail
+
+
+=== Materials
+
+
+=== Physics
+
+
+=== Rendering
+
+
+=== Spatial
+
+
+=== Terrain
+
+
+=== Visibility

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

@@ -0,0 +1,18 @@
+
+
+== Atom2DEditor
+
+Editor for 2D game based in JME3, Atom, Atom2D technologies.
+
+
+
+==== Inspired by:
+
+Unity2D
+
+
+Sprite
+
+
+Web game editor : 
+

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

@@ -0,0 +1,161 @@
+
+
+== Atom Ex framework Introduction
+
+*Hi Monkeys,*
+*Atom Ex* framework helps you biggest steps to make your applications scale to web and distributed computing!
+
+
+
+
+
+
+
+=== Idea & Buzz
+
+*Bigger, more powerful with ease*
+
+[quote]
+____
+From Data Central and Web's battle field, end up in game developing, I've dreamt about games and applications that scale its self in a snap. At first, something like a render-farm to accelerate 3D rendering pipeline or baking lightmap, massive level entities computing to save 3D artist lives, then may be something like 3D collaborative editing enviroment…
+____
+
+Initial Ideas:
+
+
+*  Get to the cloud with ease, Spring-like but not just Spring
+*  Framework for games and apps(3D) 
+*  Nextgen techs
+
+But technically, is something like this possible at all????
+
+
+*Yes*, with helps of creative design of tools and frameworks, workflows and lastest technologies!!!
+
+
+link:http://en.wikipedia.org/wiki/Model-driven_architecture[http://en.wikipedia.org/wiki/Model-driven_architecture]
+
+
+link:http://en.wikipedia.org/wiki/Data-driven_architecture[http://en.wikipedia.org/wiki/Data-driven_architecture]
+
+
+.  The first thing that most important to make this idea possible: *Everything are data*, including source code. 
+.  How can it be? Yes, it can if source code are very *generative* , means it can be generated in this way or others. In fact, *generative* is also a key. 
+.  Every aspect of this software development framework involving different kinds of auto-generating. Once again, *automatic* instead of manual is a key
+.  Keep in mind *this is not magic but the lastest technologies* , means it's new, and some people also can not believe it real :p That's easy to understand. 
+
+In fact, current implementation of AtomEx only cover a very small part of the automatic distributed game development but its potential is large. 
+
+[quote]
+____
+As examples for distributed computing, I made a 3d rendering farm and a lightmap baker for demostration that show well the power of its theory and also helpful but not show much the automatic aspect. [quote]
+____
+In constrast, the example 1000MMORPG show only 1000 LOC (lines of code) of Groovy without the AtomEx's code base can make an full-scale MMORPG with Networking, Multi-nodes Database, servers, monitors, clients, SDKs , much more… which show the power of automatic code generation and model centric architecture. 
+____
+
+____
+
+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]
+
+
+The most attractive and impressive part is this is not a “config hell framework, somehow Spring-like mechaism, but Convention over configuration…
+
+
+[to be continued]
+
+
+
+=== Features
+
+
+=== Architecture and components
+
+Here are its architecture and components.
+Atom Ex Core highlights:
+
+
+*  Beans: Java at its finesse
+*  Generative | Automative as its insistent characteristic
+*  Dependency | Component injection: For modular enterprise software
+*  Utilize the best open-source projects on earths
+*  Meta widget: for a flexible presentation solution
+*  Polymorphing via interfacing software architecture.
+*  Event base, messaging non block 
+*  Paralel ,utilize even GPU
+
+Atom DB : Generate all DAO, configs for persitent. One code, run anywhere.
+
+
+*  Bridge to ORMs : Cayneene , Hibernate
+*  Bridge to NoSQL : Casabranda , Neo4j
+*  Leverage all with “useful EJB3,Spring ideas and model driven architecture
+
+Atom WebScale : play with only the best in Web world, generate game's website front|admin in few clicks
+
+
+*  Bridge to Wicket
+*  Bridge to Grails
+*  Bridge to Play
+*  Bridge to SpringMVC
+*  Experiment with HTML5 and JavaScript almighty: Node.js , lot more… <<WebScale,WebScale>>
+
+Atom Cloud : Modulize the game | application project and deploy structure
+
+
+*  Bridge to Osgi
+*  Ultimate Maven Gradle automatic deployment
+*  Toward Collabrative enviroment
+
+Atom Storm : Distributed computing at its finesse
+
+
+*  Storm: as its best corporator
+*  Hadoop and folks as the runner-up
+*  Come with ready to use tools help 3D rendering and game creating pipeline
+
+Atom Universal : Bring it all to common open infrastructure
+
+
+*  Full distributed packages of the Atom framework online
+*  Dynamic flexiable linkage that can suite almost teamwork game developing projects
+*  Simple but powerful Pipeline | Workflow designer
+*  A lot of examples , architype , free stuffs
+*  Code link to OpenShift, Heroku, GoogleAppEngine, AppFrog,… via Git, SVN , Mecury
+*  Utilites to use standard deploy solutions …
+
+Atom Star Dust:
+
+
+*  Smallscale version of those mentioned components, toward mobile devices and web-base, HTML5 games for ex.
+*  Every where, small tiny, fastest, embed inside others, stick together well. 
+*  This is specific component of Atom framework really show up as “Atom
+
+
+=== Vision
+
+Without trying to bloat, this is a most attractive point of the whole framework - Atom. 
+
+
+You have open computing power, open infrastructure, open storage and everything under your hand and work as you wish!
+
+
+Toward “cloud for game development and gaming, even better than that! 
+
+
+Metaphorically, it's the sweestest result you can milk from the open source cows :p (Sorry if the idiom offense anyone) 
+
+
+Yeah, money somehow..? But Open spirit in its heart! 
+
+
+
+=== Other open-source dependencies
+
+…
+
+
+<<jme3/atomixtuts#, Atomix Series of game making>>
+
+
+GOTO <<jme3/advanced/atom_framework#,This Part of Atom framework >>
+

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

@@ -0,0 +1,256 @@
+
+
+== AtomExAssets
+
+The future assets pipeline for JME3 games!
+
+
+
+=== Features
+
+*  Real pipeline
+*  Multi sources & Multi targets
+
+
+=== The "real" pipeline
+
+Pipeline is a common term in computing and also asset making. From sattelite view, pipeline is progresses between input and output.
+
+
+image:http///storm.incubator.apache.org/images/topology.png[400px,with="",height=""]
+
+
+Here in game we talking about Assets aspect, mostly! 
+
+
+In real world, converting-processing data and assets also require amount of times, efforts and cause headaches, almost comparable to making data and assets.
+
+
+
+
+
+
+==== Converting
+
+Converting between things is a hard problem:
+
+
+*  Semantic: “things are different “in contexts. 
+*  Incompatible: Converting almost one-direction only. Converter programs sometime not reliable and not support your data
+*  Hidden: Some format is unknown. Some require commercial and $$$
+*  Fault-tolerant: Currently almost asset pipeline is easy to fail and do not support recovery.
+
+
+==== Processing
+
+Processing again is require a lot power:
+
+
+*  Time: Did you ever generate lightmap or PVS? - It may take a long long wait and easy to fail.
+*  Power and units: Did you ever render a movie? - It may require a render farm.
+*  Connections: Is there anything has to transfer between units? - It may delay the whole progress.
+
+
+==== Innovations
+
+AtomExAsset try to leverage pipelines from ideas inspired:
+
+
+
+===== From Preon
+
+Bit stream language
+
+
+
+===== From DataTurbine
+
+Real-time data over network
+
+
+
+===== From Distributed computing
+
+link:http://storm.incubator.apache.org/[http://storm.incubator.apache.org/] -
+
+
+
+===== From Other CCDs and Engines
+
+3DSMax and Autodesk programs: Render farm integrated.
+
+
+Blender: DNA structure
+
+
+Unity: Metadata and SVN integrated
+
+
+
+=== Multi sources & Multi targets
+
+
+== First look
+
+
+=== Slides
+
+
+
+
+
+=== Architecture
+
+
+=== Supported sources & targets
+
+
+=== Quickstart
+
+
+==== Unified Format? How about NO
+
+“Unified Format (use one format to encoded, decoded all kind of assets) is actually a nice idea but it's not real useful in real life situtations (or not even possible?)
+
+
+AtomExAsset in other hand has unified pipeline via: Codecs, Flows, EntryPoints. Its “unified data are actually a temporial data which has meta-data embeded.
+
+
+
+==== Temporial scene data
+
+
+==== Codecs
+
+Models
+
+
+Textures
+
+
+Animations
+
+
+Basic usages
+
+
+
+==== EntryPoints
+
+EntryPoint is a higher abstract level of AssetKey where we accept the fact that Assets is not actually separated but reference in nested way, via each other and form a topology. We are talking about batch solutions which are very popular in real-life gamedev, and a way to integrate the flow of assets to the normal pipeline…
+
+
+A lot of AAA games of big company relied on packed and streaming assets (online, from disks..). This assets usually get loaded by chunks instead of a whole at a time, make it possible to process as fast and smooth as possible.
+
+
+You can see one simple example of the situation when:
+
+
+*  We reference to a Texture assetkey of a single Tile: assetManager.load(“tile1.png);
+*  We later make a texture atlas of Tiles: tiles.png
+*  How can we reference to the original tile the old way, ignore the fact that it got batched!?
+
+Texture atlas for ex and all kind of batching assets (pack, atlas, uber …) are techniques to optimize/boost  load time and real-time performance. Obfucasion, encoding add an extra layer technique that hide the real data from the back-end user; who shouldn't touch that data and modify them.
+
+
+Also the always processing nature of the the asset in Atom pipeline require “dynamic entry point which AssetKey's abstraction is not enough. EntryPoint and Flow are two new concept in the playground that you should take time to get familiar with.
+
+
+
+==== Flows
+
+
+==== J3A
+
+.j3a (see, it looks like j3o) stand for “Alternate Automatic Assets is not actually format, but a meta-data or entry point in the asset system. One can use .j3a as entry point to load what ever he want with just the name, for ex:
+
+
+....
+ assetManager.load("monkey.j3o")
+....
+
+is equal with:
+
+
+....
+ assetManager.load("monkey.j3a")
+....
+
+but the later has extra effects:
+
+
+*  It put a update watcher over the entry point 
+**  the file in filesystem
+**  if you has config for that entry to “link to another remote point (git, remote asset central), it actually manage the linkage for you
+
+*  It manage the flows of the loading progress of that entry
+*  It manage the avaiablility, validation, necessarility of that entry if you are in a streaming scenario
+*  It let the assets pipeline fault tolerant.
+**  So if the entry point is not available yet, you has a place holder util the file is available. The “holding back effect also can be set if need
+**  If the request to the entry point actually timeouted, cached assets are used 
+
+
+
+==== Usage along with the "official" asset pipeline
+
+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.
+
+
+“
+
+
+Way1 - Atom over JME3: Put assetManager under an entry point, let call it “SEP - StaticEntryPoint.
+
+
+....
+ assetManager.load("SEP\")
+....
+
+Way2 - Atom with JME#:
+
+
+....
+ assetManager.load(".j3a")
+....
+
+
+== Documentation
+
+
+=== Write encoder & decoder
+
+Models
+
+
+Textures
+
+
+Animations
+
+
+Basic usage
+
+
+Preon reference:
+
+
+link:http://preon.codehaus.org/preon-binding/apidocs/1.1-SNAPSHOT/nl/flotsam/preon/codec/package-summary.html[http://preon.codehaus.org/preon-binding/apidocs/1.1-SNAPSHOT/nl/flotsam/preon/codec/package-summary.html]
+
+
+
+=== Manage dataflow & turbine
+
+
+=== Server & Nodes
+
+AtomExAssets ultimately use Building tools and Framework to help Java developer doing Game assets!
+
+
+Beside of Defacto of the building tools: Ant & Maven, the new rising star Gradle. AtomExAssets also use the powerful framework:
+
+
+link:http://www.go.cd/[http://www.go.cd/]
+
+
+image:http///www.go.cd/images/home-image1.png[home-image1.png,with="",height=""]
+

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

@@ -0,0 +1,81 @@
+
+
+== Atom Scripting
+
++++<abbr title="Application Programming Interface">API</abbr>+++ and ultilities for various scripting language upon Atom framework.
+
+
+
+=== Initial Idea
+
+
+==== Why limited your self in Java?
+
+Java has its quirk, the others JVM language try to fullfill it!
+
+
+
+==== Scripting - Polygon expanding?
+
+
+==== NEED OF POWERFUL SCRIPTING SYSTEM
+
+
+
+
+
+=== OVERVIEW
+
+Leverage Java syntax and capacities through scripting (or polygot expanding) with below languages:
+
+
+
+==== Features:
+
+Groovy
+
+
+Scala
+
+
+JLua
+
+
+Jython
+
+
+JavaScript
+
+
+Clojure
+
+
+
+=== TECH PROBS
+
+
+==== Incompatible
+
+
+==== Conccurent problems
+
+
+== DESIGN & ARCHITECTURE
+
+Slide
+
+
+
+== IMPLEMENTATION
+
+Slide
+
+
+
+== Scripting tutorials
+
+<<jme3/scripting#,Scripting tutorial>>
+
+
+
+== DOCUMENTATION

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

@@ -0,0 +1,3 @@
+
+AtomSDK
+

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

@@ -0,0 +1,166 @@
+
+
+== Character customization Introduction
+
+This is an introduction of Character customization tool of Atom framework
+
+
+<<quickstart#,quickstart>>
+
+
+
+=== Ideas & Features
+
+
+==== Ideas
+
+The initial idea of Character customization is: We (human) are soooo *similiar*!! 
+
+
+The second idea: *resuable* and *composable*!
+
+
+.  Cloths, skins, 3dmodels, animation.. are components of a whole, which made up character
+.  The same ideas with component oriented architecture
+
+So to reduce a very big workload of data and assets need for a game with vast data of character (football players, etc…) More over we can support and encourage gamer to “build their own character! This is how we handle the situations, similiar scenario can happen in a MMOs.
+
+
+
+==== Features
+
+*  Customize parts of characters (body, face, weapon) in gender | race (male - female, human - animal…), various height, weight!
+*  Customize cloths ( shirt, skirt) and their appearance (color, decal) . The cloth will fit its wearers!
+*  Customize the face with animation, emotions ( eyes, nose, mouth ) with (smile, angry …) goto <<facial#,facial>>
+*  As close as seen in current AAA games, open to MMORPG and social games.
+
+
+
+
+<<jme3/atomixtuts/kickgame/cc#,cc>>
+
+
+
+== AtomFacial framework - First look
+
+
+=== Features
+
+.  Template: Slot, Part are “place and “item just like textbox, choicebox in a form.
+.  Composing: Provide Node base way to define Customable parts, material and assets for CC. A mesh can be stiched together again after composing.
+.  Optimization : Compress texture space, mesh verticles
+.  Transformation: Provide way to include mesh morph or bone transformation can be describle in Blender, Free form deformation to make fitable clothes.
+.  Paint and Projection: support layered paint and decal projection (box, cylinder, sphere) in mesh surface, can be baked afterward.
+
+
+=== Screenshots & Video
+
+image:youtube_fcf6grenolg[youtube_fcf6grenolg,with="",height=""]
+
+
+
+=== Techniques
+
+*1) Blend shape* : 
+
+
+*2) Bone* : 
+
+
+*3) Free form deformation*: 
+
+
+
+=== Problems
+
+*1) Blend shape* : 
+
+
+I saw that going to be added into the core soon. So exciting, that will help a tons, as soon as finish, I will make a patch to help import blend shape from blender too. One thing I still have to consider is: Can we make a type of Mesh that save a whole topology from Blender or other CAD and then become the base mesh for futher manipulate?
+
+
+*2) Bone* : 
+
+
+I saw the current behavior of Bone, SkeletonControl are quite limited. I remember once @nehon explain that we don’t save the Length of the bone, but the trans/rot/scale just like a mat4… In fact, we can save more information in a Bone, and it will help tons when it come to a situation that someone want to manipulate the bone his self.
+
+
+_setUserControl_ didn’t sastify me cause I force me to patch the whole animation system just because I want to scale a bone up and down (ex: bigger nose for a character), and sync that with the existed animation. You can say it’s just my very own problem but …
+
+
+*3) Free form deformation*: 
+
+
+For the need of cloth customization, I made my self a quick FFD system, in fact, it works extactly like a set of bones still have lengths and envelops on them. But in the end, once again I have to hack into the Mesh class and other things, just because a lot of private and final methods… It’s kind of sad that it should not be that hard for the engine users to add more features to the engine if the user want to.
+
+
+At the end, I just want what I want, that mean I just want things work if it’s really easy, silly me. So is there another way around to make those 2 simple things?
+
+
+1) Scale/Translate/Rotate a bonebut preseved the current animation. ⇒ If yes, go for Characer custumization and facial…
+
+
+2) The mesh class is the center of the system, we should provide a way for people to build in from scratch or preseved topology. May be another type of Mesh, like HalfEdge mesh. If the answer it’s No need for now just consider it once in the future (We are not just making game for the moment)!
+
+
+
+=== Architecture
+
+
+=== Components
+
+
+== Manuals
+
+Go Quick 
+
+
+Go in depth
+
+
+
+=== Basic video tutorials
+
+
+=== In depth
+
+
+==== Quickstart
+
+
+==== Asset making
+
+
+==== Programming
+
+
+== Researches & Papers
+
+This is a short list of Researches &amp; Papers
+
+
+I have a Character customization system which i've plan to be quite complete. I reviewed a fews character system including:
+link:http://www.youtube.com/watch?v=RO8GIoRLGa0[http://www.youtube.com/watch?v=RO8GIoRLGa0]
+
+
+*  Perfect World
+*  APB: Reloaded
+*  Aion
+*  Star Trek Online
+*  Champions Online
+
+Some technical articles:
+
+
+* link:http://www.heroengine.com/heroengine/dynamic-character-systems/[http://www.heroengine.com/heroengine/dynamic-character-systems/]
+* link:http://hewiki.heroengine.com/wiki/Character_Design_and_Development[http://hewiki.heroengine.com/wiki/Character_Design_and_Development]
+* link:http://anticto.com/[http://anticto.com/]
+
+
+== Alternatives
+
+
+=== Opensource
+
+
+=== Commercial

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

@@ -0,0 +1,45 @@
+
+
+== Citygen Introduction
+
+Geometric generator, editor and urban buildings, city simulation. All in one
+
+
+Powered by AtomCore, AtomAI, TopoMesh and JME3.
+
+
+
+==== Inspired by
+
+CityEngine
+
+
+CityGen
+
+
+Other CCD
+
+
+
+=== Features
+
+
+==== Shape grammar
+
+
+==== Simulation
+
+
+==== Optimization
+
+
+== First look
+
+
+=== Generation
+
+
+=== Simulation
+
+
+== Documentation

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

@@ -0,0 +1,186 @@
+
+
+== Codegen Introduction
+
+Code generator for various - cross platform programming languages and paradims. All in one!
+
+
+Powered by AtomCore and JME3.
+
+
+
+==== Inspired by
+
+ECore
+
+
+UML
+
+
+MetaWidget
+
+
+Other game engines and editor: UDK, Unity, Blender, GameMaker…
+
+
+Other node base editor: 
+
+
+Web world: 
+
+
+
+=== Features
+
+Node & Flow & Graph base
+
+
+Model base
+
+
+Scope & Instruction & Control base
+
+
+
+=== Comparasion
+
+
+==== VS MetaWidget OIM
+
+link:http://metawidget.org/[http://metawidget.org/]
+
+
+is for generating UI from objects. 
+
+
+*CodeGen* is for generating data (objects) from (data) objects.
+
+
+
+==== VS EMF
+
+link:https://www.eclipse.org/modeling/emf/[https://www.eclipse.org/modeling/emf/]
+
+
+link:http://www.eclipse.org/ecoretools/[http://www.eclipse.org/ecoretools/]
+
+
+is for model based generation.
+
+
+*CodeGen* works upon EMF and also support others: flow base - scope base paradigm.
+
+
+CodeGen tools toward Netbean instead of Eclipse to suite with JME3's SDK. Also CodeGen toward Games, not general applications!
+
+
+
+==== VS Morph/ BeanMapping / ORM
+
+Work in higher level than those.
+
+
+That's said!
+
+
+*CodeGen* work in higher level, solve other problems and depends on MetaWidget, EMF, Morph, BeanMapping and ORM.
+
+
+
+== First look
+
+
+=== Generation
+
+link:http://en.wikipedia.org/wiki/Code_generation_%28compiler%29[http://en.wikipedia.org/wiki/Code_generation_%28compiler%29]
+
+
+Atom support code generation from multiple sources and to various targets to help speed up and unite production pipeline. CodeGen - Ultimate tools for code genration corporate with AtomExAsset - Ultimate tools for game assets management is 2 facilities in charge for the job.
+
+
+Sources
+
+
+*  UML
+*  ECore
+*  Java code or Java classes with annotations
+*  Code gen diagrams (modified UML diagrams for games)
+*  3D Model and assets
+
+Targets
+
+
+*  Other Model format - via ECore, UML
+*  Groovy or Java - via ECore, UML, ANTLR
+*  Java bytecode - via instrument and transformation ASM
+*  JavaScript - via GWT, ANTLR (supervisor translation)
+*  StringTemplate, XML, Text, Configurations … and other textbased - via StringTemplate
+*  Assetpack and other kind of assets - via processing pipeline
+
+
+=== Simulation
+
+
+== Architecture & Designs
+
+
+=== MetaWidget Architecture
+
+link:http://metawidget.sourceforge.net/doc/reference/en/html/ch02.html[http://metawidget.sourceforge.net/doc/reference/en/html/ch02.html]
+
+
+link:http://metawidget.sourceforge.net/elevator.php[http://metawidget.sourceforge.net/elevator.php]
+
+
+“
+
+
+
+=== EMF Architecture
+
+link:http://wiki.eclipse.org/index.php/EMF/FAQ[http://wiki.eclipse.org/index.php/EMF/FAQ]
+
+
+
+
+
+
+=== CodeGen Architecture
+
+The initial idea of CodeGen is “there is similarity between two, there is a transform available, learnt from above.
+
+
+Also take a look at wisdoms and <<jme3/advanced/atom_framework/atomcore/algorithms#,Algorithms>> which AtomCore sketchs for Generation:
+
+
+*  [Math] A function from one set to another set.
+*  [Physics] Energy from one form to another.
+*  [Language] Translate sematic from one to another language need a dictionary.
+*  [Art] Nothing new, just a cover
+*  [Computing] Template is a good abstraction of algorimths.
+*  [Programming] DRY and open source. 
+*  [New techs &amp; trends] Topology and well defined network actually a virtue. 
+
+
+=== Layouts
+
+GraphLayout
+
+
+
+=== Builders
+
+BlockBuilder
+
+
+
+=== Blocks
+
+CodeBlock
+
+
+PlaceHolderBlock
+
+
+
+== Documentation

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

@@ -0,0 +1,286 @@
+
+
+== Comparisons between 3D libs
+
+Comparisons of general Java 3D which not tied to games and simulation
+
+
+
+==== JME3
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| JME3             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== JScience
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| JScience             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Plotemy
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Plotemy           
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Java3D
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Java3D            
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+== Comparisons between 3D game/simulation dev framework
+
+3D game/simulation dev frameworks
+
+
+
+=== Java GameEngines
+
+Some of them are free and open sourced but limited in features compared to JME3 and Atom together. In fact one can learn the architecture of Atom and plug in their engines. It's not too hard to do so as I did go through that path. The problem is the architecture is very hard to built from different concepts and loads of researches I did in the past 6 years. :)) But yes, they can of course.
+
+
+
+==== LibGDX
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Unity             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Threerings
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Unity             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Alice
+
+Alice 4 is not open sourced yet
+
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Unity             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+=== Others
+
+Some of them are free for non-commercial usages. But they're not opensourced and also just a “game engine with a lot of limitation because of this closed model. Other technologies are slowly get into their supports (and even their mind set). In my POV, those limitation's not acceptable for a rapid changing world like we living in.
+
+
+
+==== Atom vs Unity
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| Unity             
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Atom vs UDK
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| UDK               
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Atom vs CryEngine
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| CryEngine         
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+==== Atom vs HeroEngine
+[cols="3", options="header"]
+|===
+
+<a| Features      
+<a| HeroEngine       
+<a| Atom              
+
+<a| Row 1 Col 1    
+<a| Row 1 Col 2     
+<a| Row 1 Col 3        
+
+<a| Row 2 Col 1    
+<a| some colspan    
+<a|                    
+
+<a| Row 3 Col 1    
+<a| Row 2 Col 2     
+<a| Row 2 Col 3        
+
+|===
+
+
+=== Conclusion
+
+Atom and JME3 are young but the vision is clear. We want to build next gen game engine for every one with the lastest technologies!
+

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

@@ -0,0 +1,448 @@
+
+
+== Atom Framework Design
+
+This is the repository resulted of the design phase of Atom framework over years.
+
+
+
+=== Motivation
+
+It born to helps JME3 focus in *game/simulation development*, push futher in lastest/future Java technologies toward to enterpise/AAA game dev as its final goal, but compromise/ compatible with existing insfracture of JME3 and OpenGL.
+
+
+Its concept, design and archictecture inspired by AAA game engine and Enterprise Java solution.
+
+
+
+=== Overview
+
+In this page:
+
+
+.  Goal of Atom framework - which tend to expand JME3 and Java language to suite more for game dev.
+.  Problems of realtime applications (especially games).
+.  Solutions and those base platforms, frameworks that we going to use to approach those goals.
+.  Remain works and future vision
+
+
+== Design goals
+
+
+==== Overal goals
+
+*  Flexible: Game | simulations centric but not forced!
+*  Modular: Dependency injection along with Component injection
+*  Parallel: Embrace parallel computing
+*  Next gen: Come with Bleeding edge technologies and powers of Java languages
+*  Cloud ready: Scale to web and distributed computing
+*  With ease: +++<abbr title="Graphical User Interface">GUI</abbr>+++ Tools everywhere, almost zero config need
+*  Cross devices: Can run wide range of devices PC-mobile-TV.. any one that has java!
+
+
+==== Additional sub goals
+
+*  Minimum dependencies and their overlap
+*  Small footprint &amp; Efficient
+
+
+=== Slides
+
+You can view slides and download papers about the design of Atom framework here.
+
+
+
+== Real time applications
+
+Atom is designed to *MAKE* concurrent, real-time, embedded systems and *GAMES*
+
+
+
+=== Atom VS ptolemy
+
+As mentioned in the Atom framwork's introduction, Atom is actually inspired by Plotemy project link:http://ptolemy.eecs.berkeley.edu/index.htm[http://ptolemy.eecs.berkeley.edu/index.htm]
+
+
+ but it actually tend to has various different goals, techniques, mindset and approaches. The comparasion in constrast with Ptolemy will reveal a lot of Atom characteristics.
+
+
+....
+ The Ptolemy project studies modeling, simulation, and design of concurrent, real-time, embedded systems. The focus is on assembly of concurrent components. The key underlying principle in the project is the use of well-defined models of computation that govern the interaction between components.A major problem area being addressed is the use of heterogeneous mixtures of models of computation.
+....
+
+*VS*
+
+
+....
+ Atom is designed to **MAKE** concurrent, real-time, embedded systems and **GAMES**. So it focus more in code generation, profile, monitoring; focus more in graphics, physics, **player experience**... etc.   Underlying, it borrow quite a bunch of concepts that built in Ptolemy (not codes!).
+....
+
+
+==== Goals
+
+So the two projects' *goals* are quite overlapped but have different focus points and mindset!
+
+
+*  Atom has no or less concern/ interests about mathematic/ physics correctioness ( so simmulations) but the graphics side and overal behaviors.
+*  Atom has open-source spirit… but not academic!! You can see Plotemy is quite “complicated and not very popular as it provided for academic first; in constrast, Atom is broadcasted for every one to use and to make games as kids in sandboxes. 
+
+
+==== Techniques differencies:
+
+*  Atom not “just depend on well-defined models!
+*  Atom use simplier models, …but sometime simplier is better! 
+**  Simplier Entity model (not abstract out of Java object)
+**  Actor model is not as abstrat also actually from threaded enviroment
+**  No contract in Systems, the study of Systems conections and interactivities are though data-driven analysising only, that's it, a dataflow monitoring system over working system.
+**  Timming: Because of the lack of interests in math/ phycics, time model and precision model is undefined but also from Java platform.
+
+*  Those above and its core techniques that you can find below, lead Atom to be less independent from Java but also has well embeding characteristics of Java languages and run-time enviroments. So can say Atom is built directly on top of Java with no hesitate!
+
+
+=== Atom VS JScience
+
+Atom also depends in Javolution and has some parts from JScience code base but once again the purpose, Atom focus in Games and simulations… Also a lot of techniques Atom is different from one used in JScience.
+
+
+One can also see that Atom fullfill the lack of JScience's experimental Game package. :)
+
+
+
+=== Target Devices & Platforms
+
+
+==== PC
+
+
+==== Mobile
+
+
+===== Android
+
+
+==== Web
+
+
+===== HTML5 and WebGL
+
+
+== Problems
+
+
+== Solutions & Frameworks & Platforms
+
+In Java, a lot good opensource projects are already provide solutions for various challanges in software developments. The problem is how to glue those gems together in appropriate way and result in efficient, good quality product - Saving time and efforts.
+
+
+
+
+
+For example, AtomCore module depends in these high quality libraries:
+
+
+*  JME3
+*  Common Java JSR annotations:
+*  Apache commons 
+**  Lang
+**  Configurations
+**  BeanUtils
+**  Collections
+
+*  Google's 
+**  Guava:
+**  Guice: Dependency injection
+**  Snappy:
+**  LevelDB
+**  Auto
+
+*  
+
+Other require pieces are write from sk
+
+
+
+== Atom framework Design course
+
+This section is dedicated to explain some idioms, patterns, and long term solutions for problems and each design goals, structures.
+
+
+
+=== Game and real-time application
+
+
+==== Cross game-genre elements
+
+From an abstraction level, a Game- a special kind of software (almost always):
+
+
+*  composed by Entities, and their Stage; 
+*  where Actions happen in a Cycle, procedure Events;
+
+A little bit more detailed, Gameplay is the way player play the Game, has:
+
+
+*  Logic:
+**  Trigger: in which Conditions, active some appropriate Action, as primitive brick.
+**  Rule: the laws, restrictions form the game rule which player, entities obey.
+
+*  Routines: Situations/ Events/ Actions that happen in the game Cycle.
+**  Story/Cinematic mode: When player just watch the game like a movie.
+**  Interactive mode: When player interact with the game world
+
+*  Control: The way player handle their entities
+*  League: 
+**  Single: Infos, score, rewards stick to an individual 
+**  Multi: The way players join, left, make friend and interactive and play together…
+
+*  Status: Way to pause/continue , save/load current game
+
+The game “software should be published in specific enviroment, it then has:
+
+
+*  Configurations : appropriate settings for specific enviroment, device.
+*  Data : appropriate size and format
+
+
+==== CPU-GPU interactions
+
+
+==== Java-Native interactions
+
+
+==== Timing
+
+
+==== Cycle
+
+
+=== AtomCore Architecture
+
+The Core is the part that focus in *Game and real-time application*. It declare
+
+
+You can read more about the Core architecture here.
+<<jme3/advanced/atom_framework/atomcore#,atomcore>>
+
+
+
+=== Design patterns & Programming paradigms
+
+Consider research through this trusted resources before we go deeper into Atom architecture and where/why/how it apply each Design patterns:
+
+
+<<jme3/advanced/atom_framework/design/patterns#,patterns>>
+
+
+
+=== Programming aspects
+
+
+==== Java, but not just Java
+
+The most “Java things in AtomCore is Bean and Properties. Two pure Java data type which are very useful in Game world. Bean is for game object modeling and Properties for configuration.
+
+
+Of course, other Java technologies are also used but not mentioned because it's not nessesary. But Bean and Properties are the two techs that heavily used!
+
+
+“Good Java extensions used in AtomCore 0.2+ is:
+Guava:
+
+
+*  Bring Eventbus, network in a snap
+*  Collection, Fluent, functional syntax and flavour to Java.
+*  Guava also support Cache, reflection and more low level operations
+
+Guice: bring Dependency injection, better unit test, refactoring in a lightweight manner.
+
+
+Groovy is a JVM language and intergrated deeply with AtomCore, most appreal as Scripting language but remember it also can replace Java, or seen as Java. Groovy also offer much more of superb things.
+
+
+
+==== Code vs Data
+
+For big game, the amount of Data required can be so much. Mean while the complexity of code also rise fast, as the result of data increasing!
+
+
+At some point, we have to find a solution to reduce “manual Data + code making and maintaining. That where “generative code also can be seen as a kind of Data was born. This called Data-driven architecture (solution). In AtomCore 0.2, it have features to support this trend.
+
+
+
+==== Around Bean
+
+
+For example:
+
+
+*  AtomEX : the bridge to AKKA Actor model also use POJO as its candidate
+*  EJB leverage…
+*  Fx: use POJO as its effect elements
+
+Here is a brief explaination why Bean/ POJO is choosed to be the Core of Atom framework?
+
+
+....
+As built in Java technologies, Bean/ POJO is the only "consider good" solution as:
+**"the bridge"** **from Java OOP to COP**, **from Java OOP to AOP**
+....
+
+....
+also can be seen as 
+**from Object oriented programming to Data oriented programming**
+**from Object oriented programming to Aspect oriented programming**
+....
+
+....
+or **Code but also Data**...
+....
+
+
+=== Polygot programming
+
+....
+ I want Best of both worlds!!
+ (.. if it's possible?)
+....
+
+Atom in its core try to be polymorphism (polygot programming), to suite with OOP, COP, AOP or functional … Yeah, it's java after all but good kind of Java.
+
+
+Because AtomScripting and others use Groovy, so it inherit (a lot of) polygot capacity from Groovy.
+
+
+Read: link:http://groovy.codehaus.org/Polyglot+Programming+with+Groovy[http://groovy.codehaus.org/Polyglot+Programming+with+Groovy]
+
+
+
+==== Functional reactive programming
+
+
+==== Flow based programming
+
+
+==== Component based programming
+
+
+==== Composite based programming
+
+
+==== Data-driven & Model-driven & Domain-driven
+
+
+=== Modular architecture
+
+....
+ I want to reuse (or DRY)!!
+....
+
+Take a look at a JME3 game, Manager for example, what if you want the two manager's work together but loosely depend on each other, or what if you want the State to direct the Manager to do something but have minimal informations about them…
+
+
+More abstract, whenever you have some kind of Service, which is loosely depend on each other, you should try Dependency Injection link:http://martinfowler.com/articles/injection.html[http://martinfowler.com/articles/injection.html] .
+
+
+That's where Guice help in the big picture.
+
+
+
+==== Dependency injection
+
+link:https://code.google.com/p/google-guice/[https://code.google.com/p/google-guice/]
+
+
+
+==== Component Injection
+
+link:http://wiki.apidesign.org/wiki/Component_Injection[http://wiki.apidesign.org/wiki/Component_Injection]
+
+
+
+==== Dependency injection VS Component Injection
+
+link:http://code.imagej.net/gbh/lookup/DependencyInjectionandLookup.html[http://code.imagej.net/gbh/lookup/DependencyInjectionandLookup.html]
+
+
+
+==== Dependency management coolness
+
+So what's cool about dependency in real-time application and game that Atom included…
+A lot of things, but let me point out fews: 
+
+
+*Real-time dependency* is a new feature for game developing…
+Imagine that even the game just can load part of assets, with the other are delayed or missing, the dependency graph can help the game cycle continue to run, part of it in the mean time. 
+
+
+In fact the dependency graph can be considered the topo structure of JME assets dependency graph before it built, means hard links via references. Now even when the assets graph are just partly loaded, the game can run because it know a resolution to safety resolve the assets graph and scene graph afterward.
+
+
+*Enterprise features*
+You can imagine how Atom framework tend to bridge JME game and the Web universal. It's not so hard in fact. Cause Java enterprise technologies are already there to use. Lot of them are built on the top of Dependency injection and Inversion of control (or else)… I really like dependency injection but I can not agree that i should always couple with IoC per se. This will be discuss later in this documentation
+
+
+
+== Enterprise facilities
+
+
+==== Services, Dependency and Decoupling
+
+The world of enteprise evolve Modular paradigm a lot to link services (database, configurations, network protocols, web…) and help they work together in one application. 
+
+
+
+=== Available Services
+
+Try AtomEx
+
+
+
+==== To Database
+
+
+==== To other repository
+
+
+==== To configurations
+
+
+==== To web
+
+
+== Monitoring and development workflow
+
+
+== Future vision
+
+
+== References and Inspiration
+
+Atom framework's design is inspried by:
+
+
+*  Game Engine Architcture book
+*  Game Programming gems serires
+*  AI Game Engine book
+*  AI Game Wisdom book
+
+other GameEngine that I did use:
+
+
+*  UDK
+*  Unity
+*  CryEngineSDK
+*  JavaScript game engines : CraftyJs, GameQuery ..
+*  Flash game engines : Starling ,
+*  … dozen of close-source engine.
+
+other Java techs:
+
+
+*  EJB
+*  Spring
+*  Groovy
+*  Netbean
+*  … hunread of open-source projects
+
+Full researched papers list are comming.
+

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

@@ -0,0 +1,152 @@
+
+
+== [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*
+
+
+
+=== Programming paradigms
+
+Programming generally and programming languages usually designed toward a paradigm, but some of them are multi-paradigm also.
+
+
+link:http://en.wikipedia.org/wiki/Programming_paradigm[http://en.wikipedia.org/wiki/Programming_paradigm]
+
+
+link:http://en.wikipedia.org/wiki/Comparison_of_programming_paradigms[http://en.wikipedia.org/wiki/Comparison_of_programming_paradigms]
+
+
+
+==== Java programming language
+
+
+image::http///upload.wikimedia.org/wikipedia/commons/thumb/a/a4/Java_logo_and_wordmark.svg/150px-Java_logo_and_wordmark.svg.png[200,with="",height="",align="left"]
+ *Java* is a computer programming language that is concurrent, class-based, object-oriented, (mostly) imperative, structured (also referred as strictly typed)
+
+
+emoji:sunglasses Suppose that when you read this wiki you already know what Java is (partly)
+
+
+*Groovy*… 
+
+image::wiki/groovy-logo.png[200,with="",height="",align="right"]
+
+
+
+is an agile and dynamic language for the Java Virtual Machine
+builds upon the strengths of Java but has additional power features inspired by languages like Python, Ruby and Smalltalk
+
+
+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]
+
+
+
+=== Game Programming paradigms
+
+Game framework or game engines also be comparasion (along with its programming language) into some category (not include graphics capacity):
+
+
+
+==== By
+
+Entity System
+
+
+
+==== By concurrent capicity
+
+Active
+
+
+Reactive
+
+
+Interactive
+
+
+
+=== Design patterns
+
+link:http://en.wikipedia.org/wiki/Software_design_pattern[http://en.wikipedia.org/wiki/Software_design_pattern]
+
+
+link:http://sourcemaking.com/[http://sourcemaking.com/]
+
+
+link:http://wiki.apidesign.org/wiki/Main_Page[http://wiki.apidesign.org/wiki/Main_Page]
+
+
+
+=== Design patterns in game developing
+
+link:http://gameprogrammingpatterns.com/[http://gameprogrammingpatterns.com/]
+
+
+
+==== Singleton . Central . Law of detemer
+
+
+==== Lightweight & Decorator
+
+
+==== Inversion of Control
+
+
+==== Factory
+
+
+==== MVC & MVC?
+
+MPV: Model View Presenter is the two way of
+MVC Model View Controller; where Presenter is the middle-man, the mediator between Model and View know and get notificated by both Model and View.
+
+
+Talk about MVC first: Assume you know about web
+
+
+from Wikipedia link:http://en.wikipedia.org/wiki/Web_application_framework#Push-based_vs._pull-based[http://en.wikipedia.org/wiki/Web_application_framework#Push-based_vs._pull-based]
+
+
+*Push-based vs. pull-based*
+
+
+....
+Most MVC frameworks follow a push-based architecture also called “action-based”. These frameworks use actions that do the required processing, and then “push” the data to the view layer to render the results.[5] Struts, Django, Ruby on Rails, Symfony, Yii, Spring MVC, Stripes, Play, CodeIgniter, and Struts2[6] are good examples of this architecture. An alternative to this is pull-based architecture, sometimes also called “component-based”. These frameworks start with the view layer, which can then “pull” results from multiple controllers as needed. In this architecture, multiple controllers can be involved with a single view. Lift, Tapestry, JBoss Seam, JavaServer Faces, and Wicket are examples of pull-based architectures.
+....
+
+MVC Push was born in the world of “none frequent” and not suite well for kind of application almost done update every-frame. So there is some kind of Event,Action embed on it.
+
+
+MVC Pull in another hand, suite better for “frequent update” and assume that View is the one trigger the update call.
+
+
+Back to real-time game, if you not making a chess game, almost you “are doing” a pull based MVC, or apply this pattern privately. 
+
+
+
+== Design patterns in JME3
+
+Here some analysing about patterns in JME3 world so Atom bypass or inherit them.
+
+
+
+==== Push or pull ?
+
+worth to note:
+even some part of JME3 assemble MPV, it’s not the whole!
+also for a game, apply MPV is quite annoying and also tricky!
+
+
+
+
+
+because of this cycle 
+
+
+
+== Design patterns in Atom

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

@@ -0,0 +1,273 @@
+
+
+== Atom Framework Documentations
+
+Welcome this is the main entrance of Atom framework documentation. Here you will find all the resource you need to start developing with Atom framework. First take a look at the structure of the documentation.
+
+
+
+=== Structure of the Documentations
+
+.  Architecture Design
+.  General docs
+..  Setup
+..  Coding and project structure convention
+..  Usages of SDK
+
+.  Component's docs
+..  AtomCore
+..  AtomEx
+..  AtomSDK
+..  TeeHee .. others
+
+
+
+== Download and Setup
+
+<<jme3/advanced/atom_framework/docs/setup#,Download and Setup instructions>>
+
+
+
+== Design documentation
+
+Design &amp; Architecture documentation page: 
+<<jme3/advanced/atom_framework/design#,design>>
+
+
+
+== The Code
+
+
+
+
+
+=== Programming aspects
+
+*  Java
+*  Groovy
+*  XML
+
+
+=== Polygot programming
+
+AtomCore (pure Java) supports:
+
+
+*  Functional reactive programming
+*  Flow based programming
+*  Component based programming
+*  Composite based programming
+*  Data-driven &amp; Model-driven &amp; Domain-driven
+
+Because AtomScripting and others use Groovy, so it inherit (a lot of) polygot capacity from Groovy.
+
+
+Read: link:http://groovy.codehaus.org/Polyglot+Programming+with+Groovy[http://groovy.codehaus.org/Polyglot+Programming+with+Groovy]
+
+
+
+=== How can I structure my code?
+
+....
+How can I structure my code in Atom framework and in JME3 games. What is the best practices, some patterns, pros cons and caveat?
+
+....
+
+link:http://hub.jmonkeyengine.org/forum/topic/how-to-structure-the-game-code/[http://hub.jmonkeyengine.org/forum/topic/how-to-structure-the-game-code/]
+
+
+More detailed, <<jme3/advanced/atom_framework/docs/code/structure#,Code structure explained>>
+
+
+You can also find a better examples here in my game examples:
+<<jme3/atomixtuts#, Atomix's tutorials games>>
+
+
+
+=== Code generation
+
+link:http://en.wikipedia.org/wiki/Code_generation_%28compiler%29[http://en.wikipedia.org/wiki/Code_generation_%28compiler%29]
+
+
+Atom support code generation from multiple sources and to various targets to help speed up and unite production pipeline. <<jme3/advanced/atom_framework/codegen#,CodeGen>> - Ultimate tools for code genration corporate with <<jme3/advanced/atom_framework/atomexasset#,AtomExAsset>> - Ultimate tools for game assets management is 2 facilities in charge for the job.
+
+
+
+===== Sources
+
+*  UML
+*  ECore
+*  Java code or Java classes with annotations
+*  Code gen diagrams (modified UML diagrams for games)
+*  3D Model and assets
+
+
+===== Targets
+
+*  Other Model format - via ECore, UML
+*  Groovy or Java - via ECore, UML, ANTLR
+*  Java bytecode - via instrument and transformation ASM
+*  JavaScript - via GWT, ANTLR (supervisor translation)
+*  StringTemplate, XML, Text, Configurations … and other textbased - via StringTemplate
+*  Assetpack and other kind of assets - via processing pipeline
+
+
+=== More coding convention
+
+
+=== Configurations
+
+Atom support configs based in Apache Commons Configurations:
+link:http://commons.apache.org/proper/commons-configuration/[http://commons.apache.org/proper/commons-configuration/]
+
+
+Apache Commons Configurations supported configuration format:
+
+
+*  Properties 
+*  XML
+*  JMX
+
+Additionally Atom support configuration via:
+
+
+*  Java Annotations 
+*  GroovyConfigs
+
+
+=== Scripting
+
+Default scripting language of Atom framework is Groovy. 
+
+
+Some optional groovy facilities are also included (gpars, ASM, ANTLR…) 
+
+
+
+
+
+You can also do scripting in other Java scripting frameworks like BeanScript or JavaScript.
+
+
+Scripting leverage game programming a lot. You can stay inside the running game and make changes into the game enviroment (is just one small advantage aside of other super cool features!). So read about how to do scripting here:
+
+
+link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:advanced:atom_framework:atomscripting[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:advanced:atom_framework:atomscripting]
+
+
+link:http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting[http://hub.jmonkeyengine.org/wiki/doku.php/jme3:scripting]
+
+
+
+== The Project
+
+Atom provide two editing facilities : AtomEditor for ingame editing and AtomSDK for desktop swing based in Netbean. Both of them working with a Project format and structure defined in AtomEditor structure.
+
+
+The main format to save Project informations is XML. With default settings format is normal XML, it can be set to used a multiversion XML tree (imagine git but effective in XML).
+
+
+<<jme3/advanced/atom_framework/docs/project#,Project details>>
+
+
+
+=== Project structure
+
+The project also has a folder structure (directories and files) convention just like JME3. Aware of that when coding or making assets.
+
+
+<<jme3/advanced/atom_framework/docs/project/structure#,Project structure>>
+
+
+
+=== Code or Data?
+
+First take a look at how Atom manage Data…
+
+
+<<jme3/advanced/atom_framework/atomexasset#,AtomExAsset>>
+
+
+*One question you may ask: if Atom was so Data+Model-driven and generative. Is code still code or is Data?*
+
+
+.  Code is still code in almost every situations. 
+.  Till it's sent into generation pipelines (when you hit build or so), the new code and assets are generated.
+.  In pakaging phase, code (as byte code or scripts) are packed completely in jar (or packages format). Some of them are ofucased, zipped then translate via network. They are now data.
+.  In the run-time enviroment again, they are data of the JVM to execute which instruct the machine to do something (your games)
+.  Some of data are still data the whole time :Images or 3D Models and almost Assets for examples. But because some user data can be embeded in j3o (script for example) so they are also code in other perspective.
+
+The distingish between data and code just need to be clear if you like to process on them. As long as you don't, they are same bit, forget about the differencies totally - who give a $%it!
+
+
+
+=== Project settings
+
+
+== Usage of SDK
+
+
+=== For 3D editing
+
+
+=== For project management
+
+
+=== For code generation
+
+
+== Components documentations
+
+
+=== Atom Libraries
+
+AtomCore
+
+
+AtomSripting
+
+
+AtomEditor
+
+
+Atom2D
+
+
+Atom2DEditor
+
+
+CodeGen
+
+
+CityGen
+
+
+AtomEx
+
+
+AtomExAsset
+
+
+AtomLight
+
+
+AtomAnim
+
+
+AtomAI
+
+
+AtomTestbed
+
+
+
+=== Inside AtomSDK
+
+TeeHeeComposer
+
+
+CharacterCreator
+
+
+MMO-Machines
+

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

@@ -0,0 +1,103 @@
+
+
+=== How can I structure my code?
+
+
+==== The question
+
+....
+How can I structure my code?
+
+....
+
+link:http://hub.jmonkeyengine.org/forum/topic/how-to-structure-the-game-code/[http://hub.jmonkeyengine.org/forum/topic/how-to-structure-the-game-code/]
+
+
+
+==== The pattern
+
+Read the explain about some design patterns in Design <<jme3/advanced/atom_framework/design#,design>>
+
+
+This queston evolve several patterns like Singleton, Manager, Factory and related directly to the Central idiom of Atom's framework!
+
+
+
+==== The central
+
+Now talking about the long “getManager().getSubManager().getItsManagedObject().doSomeThing()”
+Consider asking your self this when you code:
+
+
+.  Can singleton help?
+.  Can hierarchy actually help?
+.  How secure is your application, is it a game or anything else?
+.  How perfomance sensitive your game is?
+
+For this particular example, related to “Law of Demeter” that @zanval88 mentioned is about “communicating range scope” and “hiding information”, appear as “encapsulation” and “reference” in Java.
+
+
+.  If all your Manager classes is public, and referenced every where chances that they can be Singleton (read more about singleton for its downside).
+.  If not, you should nest your Manager and its ManagedObject it arbitrary order and way. Consider this for a game, it’s almost always not necessary!
+..  When you have your Managers and Object form a “tree” and obey a “cycle” or “protocol” or “common pattern”, may be contract them with an Interface or force them to extend the same base. [I DID this in my Atom framework!]
+..  Actually while a lower (near the core) Manager are more powerful and can capture the whole process, the higher level Manager (extended Manager or sub manager) know better about detail and specific aspects. The split should be carefully thought first to avoid un necessary burden of too much Managers. Personally, I usually think about an interesting example about a society with many cops and few citizens to imagine about this balance.
+
+.  For part of the game, when security are most important but not the performance, or for external services. Long indirect call is the most appropriate method, because of the availability (something should be injected, lazy loaded…) and security (some protol given, real info is hidden from our view,…etc). Without a check of availability, chance that you have NPE all the time!
+.  For part of the game that need performance. I said “a big deal of performance” you should try “singleton” for final class (and bare with its other issuses) or bet in some other flatten type of reference (little bit worse performance – one level of indirect) should also be concerned:
+..  array or list with an index. map via Class(Type) apear as Template in java … 
+...  ex: StateManager.getState(ClassName.class).doSomething(); 
+...  or even more abstract somekind of Central.get(“StateManager”).do(“ItsFunctionName”)!!! I do this in groovy and for Java 8 dynamic invoking
+
+..  evolve your hierarchy with EntitySystem paradigm
+
+
+
+==== The structure
+
+I have a strong conceptual POV about video game, which affected by cinematography a lot. Because English is not my native language I can misunderstood the real meaning of the noun but I’ve tried to find the right words in decade.
+
+
+This one is mine, maybe only me but noone else :p :
+
+
+So consider this 5 level of separation:
+
+
+.  Main : The main entry, have everything only relate to this single game, single application. Also game specific Configs should be here
+.  Core : The shared part can be used in almost every application share the same base
+.  Stage : The ‘Stage’ is the base of entities, activites and events… It’s not nessesary care about the gameplay but the World, Camera, Light and Effects, Cinematic. Stage contain most of the underlying logic, and the actors.
+.  GamePlay: The part care about the routine of the game, the player, characters, stories, items, gameactions, techtree… it’s make the game look more like a game than an normal software or a movie. Gameplay contain most of the interactive part.
+.  State : Even your game routine can be modeled by something else not States, I introduced State to be more friendly with JME3′s AppState concept. I ultilized it and leveraged it, and you should also.
+
+Others optional:
+
+
+.  *Network : For network game, blending between state, sub-routine and arbitrary events is difficult and may require other kind of paradigm, that’s why is not in Stage, but elsewhere outside.
+.  *Services: If your game use external services such as Web or IAP or something like that.
+.  *UI: UI stand for user interface, almost everygame have user interfaces but not all, so it’s also optional
+.  *Script: For scripting, in my application, I embed Groovy everywhere, but I also preseved a place to hold “tranditional” run-time script that only be awared and executed when the game is already running.
+.  *Model: If you are in a company or from a strong “standard lized” Java workflow, it’s nearly you’ll come up with some Bean like this, but it’s kind of for normal software not a game.
+.  *Generated: Also if you have to embed some XML or some generated sources
+.  *DB: Of course Database and persistent solution can be here( if not better be in the Service section)
+
+…
+
+
+The directory :
+ * src
+
+
+* my.game.name
+** main
+** core
+** state
+** gameplay
+** (*)network
+** (*)services
+** (*)ui
+** (*)others
+
+
+More detailed, You can find a better example here in my game examples:
+<<jme3/atomixtuts#,atomixtuts>>
+

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

@@ -0,0 +1,28 @@
+
+
+=== Atom framework's Managers
+
+Read about the Manager idea here <<jme3/advanced/atom_framework/atomcore#,atomcore>>
+
+
+Atom also have a lot of Managers. *Here suggestion for implemented one!*, you can call it a convention because it's not forced on you to gain more flexibility.
+
+
+Manager can has SubManagers, as a List or a Map (Hierarchy or not is not forced)
+
+
+Manager can be extended or Singleton or DefaultInstance (can be getDefault() but not a singleton) here and there. Manager all “attend” in a “cycle” but not “obey”. They can implement ICycle to mark they executor as Obey stricly to the Cycle.
+
+
+you can do Main.getManager(Class) if your Main support it, or doing the long reference getManager().getSubManager().
+
+
+You can see it as a hybrid or “no contract yet” – “not stricted to” way of implementing to get “best of both world” out of:
+
+
+.  singleton vs default vs linked instance
+.  hierarchy vs flatten component base
+.  cycle attend vs a random routine.
+
+In this implementation, I also try to have a good balance between flexibility and usefulness, clearance and performance. In the near future, when my framework is proved to be statable and useful, I will release it fully.
+

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

@@ -0,0 +1,57 @@
+
+
+=== The structure
+
+
+==== Videogame structure
+
+I have a strong conceptual POV about video game, which affected by cinematography a lot. Because English is not my native language I can misunderstood the real meaning of the noun but I’ve tried to find the right words in decade.
+
+
+This one is mine, maybe only me but noone else :p :
+
+
+So consider this 5 level of separation:
+
+
+.  Main : The main entry, have everything only relate to this single game, single application. Also game specific Configs should be here
+.  Core : The shared part can be used in almost every application share the same base
+.  Stage : The ‘Stage’ is the base of entities, activites and events… It’s not nessesary care about the gameplay but the World, Camera, Light and Effects, Cinematic. Stage contain most of the underlying logic, and the actors.
+.  GamePlay: The part care about the routine of the game, the player, characters, stories, items, gameactions, techtree… it’s make the game look more like a game than an normal software or a movie. Gameplay contain most of the interactive part.
+.  State : Even your game routine can be modeled by something else not States, I introduced State to be more friendly with JME3′s AppState concept. I ultilized it and leveraged it, and you should also.
+
+Others optional:
+
+
+.  *Network : For network game, blending between state, sub-routine and arbitrary events is difficult and may require other kind of paradigm, that’s why is not in Stage, but elsewhere outside.
+.  *Services: If your game use external services such as Web or IAP or something like that.
+.  *UI: UI stand for user interface, almost everygame have user interfaces but not all, so it’s also optional
+.  *Script: For scripting, in my application, I embed Groovy everywhere, but I also preseved a place to hold “tranditional” run-time script that only be awared and executed when the game is already running.
+.  *Model: If you are in a company or from a strong “standard lized” Java workflow, it’s nearly you’ll come up with some Bean like this, but it’s kind of for normal software not a game.
+.  *Generated: Also if you have to embed some XML or some generated sources
+.  *DB: Of course Database and persistent solution can be here( if not better be in the Service section)
+
+…
+
+
+
+==== Project source structure
+
+The directory :
+ * src
+
+
+* my.game.name
+** main
+** core
+** state
+** gameplay
+** (*)network
+** (*)services
+** (*)ui
+** (*)others
+
+
+More detailed, You can find a better example here in my game examples:
+<<jme3/atomixtuts#,atomixtuts>>
+

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

@@ -0,0 +1,76 @@
+
+
+=== Download and Setup
+
+Checklists before you start:
+
+
+....
+  You has JME3 Engine and SDK installed properly with lastest version
+  You've read the wiki and know what Atom framework is? 
+....
+
+Checkout
+
+
+....
+  Check out the source from
+....
+
+....
+      http://code.google.com/p/atom-game-framework/source/checkout 
+....
+
+....
+  Open atom-testbed-examples in the SDK. 
+....
+
+
+==== Download
+
+Jar:
+
+
+Repository:
+
+
+Update central:
+
+
+Maven:
+
+
+Gradle:
+
+
+
+==== Setup
+
+
+===== For AtomSDK
+
+
+===== For Atom TeeHee
+
+Troubleshoots
+
+
+If you can not get this basic start, don't worry.
+
+
+Read back JME3 simple tutorials first and come back. Just take 10 mins or so. :) or goto: link:http://code.google.com/p/atom-game-framework/wiki/Troubleshootings[http://code.google.com/p/atom-game-framework/wiki/Troubleshootings]
+
+
+Cheer.
+Install AtomSDK from Update Central
+Done, let's make games!
+
+
+
+=== Let's take basic tutorials here.
+
+If you 'are proficient enough with Java+GameDev?+JME3. 
+
+
+Let's go to immediate tutorials and examples here. 
+

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

@@ -0,0 +1,60 @@
+
+
+== Facial Techs Introduction
+
+Eh… What 's so fancy about those AAA games, like MassEffect, Drake and those from UDKs…?
+
+
+It's all about the face!
+
+
+....
+  Yeah, indeed. Facial animation play an important role in game industry today. I won't tell you much about how much money are spent to get that character's face talk and lively... From an artist point of view, facial and emotional behavior of human character is the point to make a game's state of art!
+....
+
+Let see how can we do it in JME3, shall we?
+
+
+
+=== Ideas
+
+*  Customize the face with animations, emotions: ( eyes, nose, mouth ) with (smile, angry …)
+*  User friendly. 
+**  For newbies 
+**  but also for professinal. especially with those who use FaceFx and UDK
+
+*  Rooms for extends and usecases ( changing art-style, more specialize for simulations…) 
+
+
+<<Researches & Papers,alternatives and researches>>
+
+
+
+== AtomFacial framework
+
+image:youtube_fcf6grenolg[youtube_fcf6grenolg,with="",height=""]
+
+
+
+=== Architecture
+
+
+=== Components
+
+
+=== Features
+
+
+== Manuals
+
+
+== Researches & Papers
+
+
+== Alternatives
+
+
+=== Opensource
+
+
+=== Commercial

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

@@ -0,0 +1,214 @@
+
+
+== FX
+
+Stand for Effects.
+
+
+Also stand for dynamic value functions f(x). 
+
+
+Inspired by 
+
+
+link:http://nodebox.net/node/[http://nodebox.net/node/]
+
+
+link:http://udk.com[http://udk.com]
+
+
+
+=== What's about the f(x) ?
+
+For various effects the game may require. Need customable, extensible way to declare input-process-ouput:
+
+
+.  dynamic generic Data, which can be procedure by various sources, signals, services
+.  dynamic generic declaration of operations
+.  dynamic generic declaration of output order
+
+Last but not least, it should be resuable, generative and composable.
+
+
+
+==== In Java?
+
+About the implementation, such as language should be under considered!
+
+
+These all requirements fit to an DSL, functional and lazy like groovy scenario, but what about java - a traditional grown as imperative language? It's like we going to implement all its core language elements for god-sake… Umh, not like that. With the help of Guava, we do it properly acceptable and scalable! But read it carefully first or mislead later!!!
+
+
+link:http://code.google.com/p/guava-libraries/wiki/FunctionalExplained[http://code.google.com/p/guava-libraries/wiki/FunctionalExplained]
+
+
+
+
+==== Focus in effects
+
+
+
+
+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. 
+
+
+Now Let's see how does it work?
+
+
+
+=== Interface & Abstract
+
+We need dynamic Data, which can be procedure through various sources, signals, services… let call the abstract which provide the data IValueProvider:
+
+
+interface IValueProvider <x,y>{
+y   value(x) return new y
+}
+
+
+Function <x,y> is the default implementation
+
+
+Function <x,y>{
+}
+
+
+
+=== Input
+
+So what can be the input?
+
+
+Single<Value> or any primitive
+
+
+List<Value> . String
+
+
+more
+
+
+
+=== Time factor & Real time application
+
+An important factor of a real time system is … time, indeed. Imagine a physic world functioning with f(t) is the primitive law. Our effects system also. Almost every effects envolve time and almost modify or procedure several positions values. It's a very common case in this scenario.
+
+
+In fact almost of the F(x) features are actually f(t) which t is the time provided by the system via update cycle. 
+
+
+Now consider this very simple physic xample :
+
+
+S = V.t 
+
+
+pos = startPos + S 
+
+
+→ pos = startPos + V.t
+
+
+We have:
+
+
+.  startPos is a Vector3f (can be localTranslation of a jme3's Spatial!). 
+.  a parameter vector V, basicly stand for the Speed
+.  t is time provided by system
+.  plus and multiply is numberical operations
+
+→ We can compute the new pos which we can use as a slide of a ball!
+
+
+In this simplest example, we should reads a mathematic equations as a “procedural process in our fx system with time as an essential key. Which later will help us build up extraordary complex effect!
+
+
+
+==== Animations concepts
+
+Here we will revised some animation concept. Kinematic and functionals.
+
+
+
+===== Timeline
+
+
+===== Keyframe
+
+
+===== Sequence
+
+
+===== Track
+
+
+=== Operations
+
+
+==== Single operation
+
+
+===== Math
+
+
+===== Add remove
+
+
+==== List operation
+
+
+===== Add remove
+
+
+===== Transfrom
+
+
+===== Indexing
+
+
+==== 3D Geometric operation
+
+
+===== Curve . Interpolator
+
+IValueProvider
+
+
+
+===== Layout
+
+
+===== Shape and formation
+
+
+===== Steering
+
+
+== Effects
+
+…
+
+
+
+=== Text Effects
+
+One of the most under rated part in almost every 3d game engine I come across is the *Text effect*. We *DO* need Text effect but it didn't have any native support. I've started by doing a lot of After effect's text effects and plugin, then trying in 3DSMax, Cinema4D, later in Processing… but I can not find one that make me feel easy to use and powerful. From some ideas borrow from those applications, I try to implement some in this framework.
+
+
+
+=== Particle Effects
+
+
+=== Cinematic Effects
+
+
+=== Color & Texture Effects
+
+
+=== Mesh & Spatials Effects
+
+
+=== Animation Effects
+
+
+=== Scripted Effects

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

@@ -0,0 +1,66 @@
+
+
+== Atom's GUI
+
+In Atom framework, I choose NiftyGUI because its much more features, expandable, have active developing status, and good friendly supports. 
+
+
+AtomGUI is the base of AtomEditor component (of Atom framework), which in turn provide easy editing support for game objects, configs and such, just like Swing does with Java's bean and Models, but in 3D with hardware accelarated.
+
+
+
+=== Additions
+
+My additions for NiftyGUI:
+
+
+*  Lightweight MVC
+**  Template framework
+**  a Groovy builder
+**  a +++<abbr title="Cascading Style Sheets">CSS</abbr>+++ (Cascaded Style Sheet) implementation (for NiftyGUI), even a LESS
+**  a simplier Localization framework
+**  GQuery stand for “JQuery in Groovy
+**  a lot of Groovy  scripting and functional sugar for NiftyGUI
+
+
+=== Ideas
+
+
+==== JavaScript and Web world Ideas
+
+It's worthy to note that I come from the Web world, and I use JavaScript everyday beside of Java. That's why I always want “good things in JavaScript world show up in game dev world.
+
+
+Things such like Template, +++<abbr title="Cascading Style Sheets">CSS</abbr>+++, GQuery, … corporate tightly with JME3 systems but with a lot of additional gun and gears. Make Nifty and JME3 a real powerful monkey as it should!
+
+
+
+=== Template and CSS
+
+Every Web framework come with a Template framework, facade and styles make the Web world colorful and attractive but +++<abbr title="HyperText Markup Language">HTML</abbr>+++ and +++<abbr title="Cascading Style Sheets">CSS</abbr>+++ is a blow-up standard!!! 
+
+
+What we trying to do here is to make is compact and usable but with posibility to enhance and extend.
+There are some “good template framework in the Java and JavaScript world:
+- Mustache
+- StringBuilder
+- Veclocity
+
+
+Also worth to take a look is : LESS (the scriptable +++<abbr title="Cascading Style Sheets">CSS</abbr>+++)
+
+
+I see much powerful can be gained if we open this direction with the combination of : JME3 + Nifty + Groovy. That's why I experiment all this stuffs.
+
+
+
+=== GQuery
+
+GQuery stand for “JQuery like in Groovy. 
+
+
+JQuery is a famous framework in the JavaScript and Web world. GQuery try to provide some of its features, immtimate its syntax and sugars, leverage by Groovy:
+
+
+*  Query, select a Node Tree (like +++<abbr title="HyperText Markup Language">HTML</abbr>+++, Nifty elements,…) with a minimal Path syntax , same as XPath
+*  Hooks to Node's (components, elements..) events with Eventbus

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

@@ -0,0 +1,81 @@
+
+
+== MMORPG Tools Introduction
+
+This is the introduction of Atoms framework's MMORPG Tools.
+
+
+
+=== Ideas
+
+A lot of MMORPG game are published but how many in java you can count?
+
+
+Do you feel so strange about it, even if we have the most powerful programming languages, techniques and toolset?
+
+
+
+==== Problems
+
+Let's talk a little bit about the problems:
+
+
+.  Too much technical problems
+.  Too much framework to use, which one is right?
+.  Too much data to make
+.  Too much people in teams, company involve the process
+.  Too much time, competitors, requirements, money, efforts, …[over 9000 probs more!]
+
+More about the MMORPG dream for small team, even invidual <<jme3/atomixtuts/mmorpg#,mmorpg>>
+
+
+
+==== Solution?
+
+Only one word (or 2): Open-source!
+
+
+So in short, what I telling you is at least it provide you a framework and a rich toolset to build up your dream game and also a production enviroment to make MMORPG!
+
+
+.  Stand in the shoulders of best open-source projects and also open-source spirit in its heart. 
+.  Also born form the most innovative ideas of game production and deployment.
+
+
+=== Buzz
+
+It's coming with:
+
+
+.  Ease of use - even your grandma can do, less code, smart tools in every single step
+.  Effiecient - increase your productivity at least 10x
+.  Scale to massive! - distributed computing, multi node , graph base database, non block event messaging, social network … much more!
+.  Trick of the trade! - Yeah, money making tricks…
+
+
+=== Current Tool?
+
+Read the full article in researches about the open-source and commercial tool for MMORPG we have currently (well, the most popular) <<jme3/atomixtuts/mmorpg/researches/toolset#,toolset>>
+
+
+
+=== Features
+
+
+=== Techniques
+
+…
+
+
+
+
+== Architecture
+
+
+== Documentation
+
+
+== Use case & Example
+
+<<jme3/atomixtuts/mmorpg#,mmorpg>>
+

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

@@ -0,0 +1,54 @@
+
+
+== Introduction
+
+This is the introduction of the RPGCreator
+
+
+Despite of its name, its not just for Role playing game!  
+
+
+Provide functions to create| test| config basic game with these key elements : characters| stories| skills| items| modes| regions… almost every game genre has them embeded partly, means cross game genre!
+
+
+
+=== Ideas
+
+*Question*: Why not a general Entity framework?
+
+
+*Answer*: You've told somewhere else that an Entity framework can compose up every thing… Yeah, quite. But for RPG, more specificly, for the idea phase, same with software modeling phase in game ( means when character concept, design, voice acting, dialoge, scripts…are made), it's not really appropriated! 
+
+'''
+
+*Question*: So you telling about the gaps?
+
+
+*Answer*: Yes, you know, thoose guys (script writer) not really need to know any technical things. They just like to made up stuffs. That's why after write down thoose ideas, this framework change the resulted data into programming materials (code, config, 3d models…). Consider this a bridge from game designers to coder, and the script writer to the teams.
+
+'''
+
+*Question*: What so Next-gen about it?
+
+
+*Answer*: Yeah, not so much. The idea at first is humble, but it will leverage so much your company's productivity. In fact, big team and big company use home grown tools to archive their scripts and ideas,intelectual properties. That's how their do it, if you know yet!
+
+'''
+
+*Question*: Enouh, show me?
+
+
+*Answer*: Here is it!
+
+
+
+=== Features
+
+
+=== Components
+
+
+== Use cases
+
+
+== Manual

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

@@ -0,0 +1,24 @@
+
+
+=== Status
+
+
+=== Issues
+
+Check google code issues checker
+
+
+link:https://code.google.com/p/atom-game-framework/issues/list[https://code.google.com/p/atom-game-framework/issues/list]
+
+
+
+=== Dificulties
+
+
+=== Not implemented (yet!)
+
+
+=== Vison
+
+
+=== Plans

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

@@ -0,0 +1,76 @@
+
+
+== TeeHee Composer
+
+
+=== Introduction
+
+
+==== Why TeeHee ?
+
+Cauz it's a funny thing. You play with it. 
+*Compose anything you want as easy as smart kids-can-do*
+
+
+
+==== What can it make ?
+
+Inspired by +++<strike>UDK and Unity's</strike>+++ , Adobe, Blender and few more…toolset and workflow. 
+
+
+Includes all of their goods but excludes or minimize their bads!
+
+
+Inspite of the fact its name is kind of funny, it's very powerful, even more than you imagine. 
+
+
+Let's me get that straight!
+
+
+
+==== Features
+
+*  Compose anything you want as easy as kids-can-do
+**  Rich toolset 
+**  +++<abbr title="Graphical User Interface">GUI</abbr>+++ everywhere - Extremely user friendly
+**  Codeless solution
+
+*  Strongly intergrated with a underlying framework
+**  Corporate with Atom framework and JME3 based techniques 
+**  Base for various expansion techiques
+
+*  But Loosely | very flexible in technical aspect: 
+**  Work as plugins
+**  Generate java, entities, xml, text configs, script, protocol… 
+**  Generic enough?
+
+*  Focus in animation, effect and cinematic aspect!
+**  Effects + sound as Adobe Premier + AfterEffect with screen + text effects 
+**  Animation + Cinematic like 3DSMax + Blender + UDK…
+**  Come with presets
+
+*  Real-time! F$#k Yeah!
+**  Everything on the screen, all inside JMP at design time.
+**  Can be configed in varios way to be realtime
+**  Save rendered movies
+**  Toward a java 3D animation composer 
+
+*  Shake and bake with Codegen for Code generation <<jme3/advanced/atom_framework/codegen#,codegen>>
+
+
+== Architecture
+
+Components
+
+
+*  Cinematic composer
+*  Dialogue composer
+*  Effect composer
+*  Particle composer
+*  Animation composer
+
+Screenshots
+
+
+
+== Manuals

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

@@ -0,0 +1,279 @@
+
+
+= Audio in jME3
+
+Place audio files in the `assets/Sound/` directory of your project. jME3 supports Ogg Vorbis audio compression (.ogg) and uncompressed PCM Wave (.wav) formats. You can use for example link:http://audacity.sourceforge.net/[Audacity] to convert from other formats.
+
+
+
+== Audio Terminology
+
+*  *Streaming:* There are two ways to load audio data: Short audio files are to be stored entirely in memory (prebuffered), while long audio files, such as music, are streamed from the hard drive as it is played.
+*  *Looping:* You can play a sound either once and then stop, or repeatedly (continuously) in a loop. +
+You cannot loop streamed sounds.
+*  *Instance:* If you play the same audio twice, the playing is queued up and jME plays one after the other. If you play instances of sounds, several instances of the same sound can play at the same time.
+
+
+== Creating Audio Nodes: Streamed or Buffered
+
+The main jME audio class to look at is `com.jme3.audio.AudioNode`. When creating a new audio node you need to declare whether how you want to load this sound:
+
+
+*  *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 the boolean to false, or using no boolean at all: 
+[source,java]
+----AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav");
+AudioNode boom = new AudioNode(assetManager, "Sound/boom.wav", false);----
+*  *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", true);----
+
+
+== Getting AudioNode Properties
+[cols="2", options="header"]
+|===
+
+a|AudioNode Method
+a|Usage
+
+a|getStatus()
+a|Returns either AudioSource.Status.Playing, AudioSource.Status.Stopped, or AudioSource.Status.Paused. 
+
+a|getVolume()
+a|Returns the volume. 
+
+a|getPitch()
+a|Returns the pitch. 
+
+|===
+
+Note: There are other obvious getters to poll the status of all corresponding setters listed here.
+
+
+
+== Setting AudioNode Properties
+[cols="2", options="header"]
+|===
+
+a|AudioNode Method
+a|Usage
+
+a|setTimeOffset(0.5f)
+a|Play the sound starting at a 0.5 second offset from the beginning. Default is 0.
+
+a|setPitch(1)
+a|Makes the sound play in a higher or lower pitch. Default is 1. 2 is twice as high, .5f is half as high. 
+
+a|setVolume(1)
+a|Sets the volume gain. 1 is the default volume, 2 is twice as loud, etc. 0 is silent/mute. 
+
+a|setRefDistance(50f)
+a|The reference distance controls how far a sound can still be heard at 50% of its original volume (_this is assuming an exponential fall-off!_). A sound with a high RefDist can be heard loud over wide distances; a sound with a low refDist can only be heard when the listener is close by. Default is 10 world units.
+
+a|setMaxDistance(100f)
+a| The 'maximum attenuation distance' specifies how far from the source the sound stops growing more quiet (sounds in nature don't do that). Set this to a smaller value to keep the sound loud even at a distance; set this to higher value to let the sound fade out quickly. Default is 20 world units.
+
+a|setLooping(false)
+a|Configures the sound so that, if it is played, it plays once and stops. No looping is the default.
+
+|===
+
+
+=== Looping & Ambient Sounds
+[cols="2", options="header"]
+|===
+
+a|AudioNode Method
+a|Usage
+
+a|setPositional(false) +
+setDirectional(false)
+a|All 3D effects switched off. This sound is global and plays in headspace (it appears to come from everywhere). Good for environmental ambient sounds and background music.
+
+a|setLooping(true)
+a|Configures the sound to be a loop: After the sound plays, it repeats from the beginning, until you call stop() or pause(). Good for music and ambient background noises. +
+*Looping does not work on streamed sounds.* 
+
+|===
+
+
+=== Positional 3D Sounds
+[cols="2", options="header"]
+|===
+
+a|AudioNode Method
+a|Usage
+
+a|setPositional(true) +
+setLocalTranslation(…)
+a|Activates 3D audio: The sound appears to come from a certain position, where it is loudest. Position the AudioNode in the 3D scene, or move it with mobile players or NPCs.
+
+a|setReverbEnabled(true)
+a|Reverb is a 3D echo effect that only makes sense with positional AudioNodes. Use Audio Environments to make scenes sound as if they were “outdoors, or “indoors in a large or small room, etc. The reverb effect is defined by the `com.jme3.audio.Environment` that the `audioRenderer` is in. See “Setting Audio Environment Properties below. 
+
+|===
+
+`AudioListener`
+
+
+
+=== Directional 3D Sounds
+[cols="2", options="header"]
+|===
+
+a|AudioNode Method
+a|Usage
+
+a|setDirectional(true) +
+setDirection(…) 
+a|Activates 3D audio: This sound can only be heard from a certain direction. Specify the direction and angle in the 3D scene if you have setDirectional() true. Use this to restrict noises that should not be heard, for example, through a wall.
+
+a|setInnerAngle() +
+setOuterAngle()
+a|Set the angle in degrees for the directional audio. The angle is relative to the direction. Note: By default, both angles are 360° and the sound can be heard from all directions!
+
+|===
+
+
+
+
+
+== Play, Pause, Stop
+
+You play, pause, and stop a node called myAudioNode by using the respective of the following three methods:
+
+
+[source,java]
+----myAudioNode.play();----
+[source,java]
+----myAudioNode.pause();----
+[source,java]
+----myAudioNode.stop();----
+*Note:* Whether an Audio Node plays continuously or only once, depends on the Loop properties you have set above!
+
+
+You can also start playing instances of an AudioNode. Use the `playInstance()` method if you need to play the same AudioNode multiple times, possibly simulatenously. Note that changes to the parameters of the original AudioNode do not affect the instances that are already playing!
+
+
+[source,java]
+----myAudioNode.playInstance();----
+
+== The Audio Listener
+
+The default AudioListener object `listener` in `SimpleApplication` is the user's ear in the scene. If you use 3D audio (positional or directional sounds), you must move the AudioListener with the player: For example, for a first-person player, you move the listener with the camera. For a third-person player, you move the listener with the player avatar Geometry.
+
+
+[source,java]
+----
+  @Override
+  public void simpleUpdate(float tpf) {
+    // first-person: keep the audio listener moving with the camera
+    listener.setLocation(cam.getLocation());
+    listener.setRotation(cam.getRotation());
+  }
+----
+
+== Setting Audio Environment Properties
+
+Optionally, You can choose from the following environmental presets from `com.jme3.audio.Environment`. This presets influence subtle echo effects (reverb) that evoke associations of different environments in your users. That is, it makes you scene sound “indoors or “outdoors etc. You use Audio Environments together with `setReverbEnabled(true)` on positional AudioNodes (see above).
+
+[cols="11", options="header"]
+|===
+
+a|Environment
+a|density
+a|diffusion
+a|gain
+a|gainHf
+a|decayTime
+a|decayHf
+a|reflGain
+a|reflDelay
+a|lateGain
+a|lateDelay
+
+<a|Garage      
+a|1.00f
+a|1.0f
+a|1.0f
+a|1.00f
+a|0.90f
+a|0.5f
+a|0.751f
+a|0.0039f
+a|0.661f
+a|0.0137f
+
+<a|Dungeon     
+a|0.75f
+a|1.0f
+a|1.0f
+a|0.75f
+a|1.60f
+a|1.0f
+a|0.950f
+a|0.0026f
+a|0.930f
+a|0.0103f
+
+<a|Cavern      
+a|0.50f
+a|1.0f
+a|1.0f
+a|0.50f
+a|2.25f
+a|1.0f
+a|0.908f
+a|0.0103f
+a|0.930f
+a|0.0410f
+
+a|AcousticLab 
+a|0.50f
+a|1.0f
+a|1.0f
+a|1.00f
+a|0.28f
+a|1.0f
+a|0.870f
+a|0.0020f
+a|0.810f
+a|0.0080f
+
+<a|Closet      
+a|1.00f
+a|1.0f
+a|1.0f
+a|1.00f
+a|0.15f
+a|1.0f
+a|0.600f
+a|0.0025f
+a|0.500f
+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,
+                reflGain, reflDelay, lateGain, lateDelay ) );----
+
+.  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>>
+
+
+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.`
+
+<tags><tag target="sound" /><tag target="documentation" /><tag target="environment" /></tags>

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

@@ -0,0 +1,224 @@
+
+
+= Audio Environment Presets
+
+Use these presets together with <<audio#,Audio>> Nodes to create different “moods for sounds. Environment effects make your audio sound as if the listener were in various places that have different types of echoes. 
+
+
+Usage:
+
+
+[source,java]
+----
+Environment Generic = new Environment(
+    new float[]{ 0, 7.5f, 1f, -1000, -100, 0, 1.49f, 0.83f, 1f, -2602,
+                 0.007f, 0f, 0f, 0f, 200, 0.011f, 0f, 0f, 0f, 0.250f,
+                 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+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} );
+CastleShortPassage = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -1000, -2000, 2.32f, 0.83f, 0.31f, -100, 0.007f, 0f, 0f, 0f, 200, 0.023f, 0f, 0f, 0f, 0.138f, 0.080f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleMediumroom   = new Environment ( new float[]{ 26, 8.3f, 0.930f, -1000, -1100, -2000, 2.04f, 0.83f, 0.46f, -400, 0.022f, 0f, 0f, 0f, 400, 0.011f, 0f, 0f, 0f, 0.155f, 0.030f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleLongpassage  = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -800, -2000, 3.42f, 0.83f, 0.31f, -100, 0.007f, 0f, 0f, 0f, 300, 0.023f, 0f, 0f, 0f, 0.138f, 0.080f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleLargeroom    = new Environment ( new float[]{ 26, 8.3f, 0.820f, -1000, -1100, -1800, 2.53f, 0.83f, 0.50f, -700, 0.034f, 0f, 0f, 0f, 200, 0.016f, 0f, 0f, 0f, 0.185f, 0.070f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleHall         = new Environment ( new float[]{ 26, 8.3f, 0.810f, -1000, -1100, -1500, 3.14f, 0.79f, 0.62f, -1500, 0.056f, 0f, 0f, 0f, 100, 0.024f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleCupboard     = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -1100, -2000, 0.67f, 0.87f, 0.31f, 300, 0.010f, 0f, 0f, 0f, 1100, 0.007f, 0f, 0f, 0f, 0.138f, 0.080f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+CastleCourtyard    = new Environment ( new float[]{ 26, 8.3f, 0.420f, -1000, -700, -1400, 2.13f, 0.61f, 0.23f, -1300, 0.160f, 0f, 0f, 0f, -300, 0.036f, 0f, 0f, 0f, 0.250f, 0.370f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x1f} );
+CastleAlcove       = new Environment ( new float[]{ 26, 8.3f, 0.890f, -1000, -600, -2000, 1.64f, 0.87f, 0.31f, 00, 0.007f, 0f, 0f, 0f, 300, 0.034f, 0f, 0f, 0f, 0.138f, 0.080f, 0.250f, 0f, -5f, 5168.6f, 139.5f, 0f, 0x20} );
+----
+
+== 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} );
+FactoryShortpassage = new Environment ( new float[]{ 26, 1.8f, 0.640f, -1200, -200, -600, 2.53f, 0.65f, 1.31f, 0, 0.010f, 0f, 0f, 0f, 200, 0.038f, 0f, 0f, 0f, 0.135f, 0.230f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} ) );
+FactoryMediumroom   = new Environment ( new float[]{ 26, 1.9f, 0.820f, -1200, -200, -600, 2.76f, 0.65f, 1.31f, -1100, 0.022f, 0f, 0f, 0f, 300, 0.023f, 0f, 0f, 0f, 0.174f, 0.070f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactoryLongpassage  = new Environment ( new float[]{ 26, 1.8f, 0.640f, -1200, -200, -600, 4.06f, 0.65f, 1.31f, 0, 0.020f, 0f, 0f, 0f, 200, 0.037f, 0f, 0f, 0f, 0.135f, 0.230f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactoryLargeroom    = new Environment ( new float[]{ 26, 1.9f, 0.750f, -1200, -300, -400, 4.24f, 0.51f, 1.31f, -1500, 0.039f, 0f, 0f, 0f, 100, 0.023f, 0f, 0f, 0f, 0.231f, 0.070f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactoryHall         = new Environment ( new float[]{ 26, 1.9f, 0.750f, -1000, -300, -400, 7.43f, 0.51f, 1.31f, -2400, 0.073f, 0f, 0f, 0f, -100, 0.027f, 0f, 0f, 0f, 0.250f, 0.070f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactoryCupboard     = new Environment ( new float[]{ 26, 1.7f, 0.630f, -1200, -200, -600, 0.49f, 0.65f, 1.31f, 200, 0.010f, 0f, 0f, 0f, 600, 0.032f, 0f, 0f, 0f, 0.107f, 0.070f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactoryCourtyard    = new Environment ( new float[]{ 26, 1.7f, 0.570f, -1000, -1000, -400, 2.32f, 0.29f, 0.56f, -1300, 0.140f, 0f, 0f, 0f, -800, 0.039f, 0f, 0f, 0f, 0.250f, 0.290f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+FactorySmallroom    = new Environment ( new float[]{ 26, 1.8f, 0.820f, -1000, -200, -600, 1.72f, 0.65f, 1.31f, -300, 0.010f, 0f, 0f, 0f, 500, 0.024f, 0f, 0f, 0f, 0.119f, 0.070f, 0.250f, 0f, -5f, 3762.6f, 362.5f, 0f, 0x20} );
+----
+
+== 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} );
+IcepalaceShortpassage = new Environment ( new float[]{ 26, 2.7f, 0.750f, -1000, -500, -1100, 1.79f, 1.46f, 0.28f, -600, 0.010f, 0f, 0f, 0f, 100, 0.019f, 0f, 0f, 0f, 0.177f, 0.090f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} ) );
+IcepalaceMediumroom   = new Environment ( new float[]{ 26, 2.7f, 0.870f, -1000, -500, -700, 2.22f, 1.53f, 0.32f, -800, 0.039f, 0f, 0f, 0f, 100, 0.027f, 0f, 0f, 0f, 0.186f, 0.120f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceLongpassage  = new Environment ( new float[]{ 26, 2.7f, 0.770f, -1000, -500, -800, 3.01f, 1.46f, 0.28f, -200, 0.012f, 0f, 0f, 0f, 200, 0.025f, 0f, 0f, 0f, 0.186f, 0.040f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceLargeroom    = new Environment ( new float[]{ 26, 2.9f, 0.810f, -1000, -500, -700, 3.14f, 1.53f, 0.32f, -1200, 0.039f, 0f, 0f, 0f, 000, 0.027f, 0f, 0f, 0f, 0.214f, 0.110f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceHall         = new Environment ( new float[]{ 26, 2.9f, 0.760f, -1000, -700, -500, 5.49f, 1.53f, 0.38f, -1900, 0.054f, 0f, 0f, 0f, -400, 0.052f, 0f, 0f, 0f, 0.226f, 0.110f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceCupboard     = new Environment ( new float[]{ 26, 2.7f, 0.830f, -1000, -600, -1300, 0.76f, 1.53f, 0.26f, 100, 0.012f, 0f, 0f, 0f, 600, 0.016f, 0f, 0f, 0f, 0.143f, 0.080f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceCourtyard    = new Environment ( new float[]{ 26, 2.9f, 0.590f, -1000, -1100, -1000, 2.04f, 1.20f, 0.38f, -1000, 0.173f, 0f, 0f, 0f, -1000, 0.043f, 0f, 0f, 0f, 0.235f, 0.480f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+IcepalaceSmallroom    = new Environment ( new float[]{ 26, 2.7f, 0.840f, -1000, -500, -1100, 1.51f, 1.53f, 0.27f, -100, 0.010f, 0f, 0f, 0f, 300, 0.011f, 0f, 0f, 0f, 0.164f, 0.140f, 0.250f, 0f, -5f, 12428.5f, 99.6f, 0f, 0x20} );
+----
+
+== 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} );
+SpacestationMediumroom   = new Environment ( new float[]{ 26, 1.5f, 0.750f, -1000, -400, -100, 3.01f, 0.50f, 0.55f, -800, 0.034f, 0f, 0f, 0f, 100, 0.035f, 0f, 0f, 0f, 0.209f, 0.310f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationShortpassage = new Environment ( new float[]{ 26, 1.5f, 0.870f, -1000, -400, -100, 3.57f, 0.50f, 0.55f, 0, 0.012f, 0f, 0f, 0f, 100, 0.016f, 0f, 0f, 0f, 0.172f, 0.200f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationLongpassage  = new Environment ( new float[]{ 26, 1.9f, 0.820f, -1000, -400, -100, 4.62f, 0.62f, 0.55f, 0, 0.012f, 0f, 0f, 0f, 200, 0.031f, 0f, 0f, 0f, 0.250f, 0.230f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationLargeroom    = new Environment ( new float[]{ 26, 1.8f, 0.810f, -1000, -400, -100, 3.89f, 0.38f, 0.61f, -1000, 0.056f, 0f, 0f, 0f, -100, 0.035f, 0f, 0f, 0f, 0.233f, 0.280f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationHall         = new Environment ( new float[]{ 26, 1.9f, 0.870f, -1000, -400, -100, 7.11f, 0.38f, 0.61f, -1500, 0.100f, 0f, 0f, 0f, -400, 0.047f, 0f, 0f, 0f, 0.250f, 0.250f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationCupboard     = new Environment ( new float[]{ 26, 1.4f, 0.560f, -1000, -300, -100, 0.79f, 0.81f, 0.55f, 300, 0.007f, 0f, 0f, 0f, 500, 0.018f, 0f, 0f, 0f, 0.181f, 0.310f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+SpacestationSmallroom    = new Environment ( new float[]{ 26, 1.5f, 0.700f, -1000, -300, -100, 1.72f, 0.82f, 0.55f, -200, 0.007f, 0f, 0f, 0f, 300, 0.013f, 0f, 0f, 0f, 0.188f, 0.260f, 0.250f, 0f, -5f, 3316.1f, 458.2f, 0f, 0x20} );
+----
+
+== 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} );
+WoodenShortpassage     = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -1800, -1000, 1.75f, 0.50f, 0.87f, -100, 0.012f, 0f, 0f, 0f, -400, 0.024f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenMediumroom       = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -2000, -1100, 1.47f, 0.42f, 0.82f, -100, 0.049f, 0f, 0f, 0f, -100, 0.029f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenLongpassage      = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -2000, -1000, 1.99f, 0.40f, 0.79f, 000, 0.020f, 0f, 0f, 0f, -700, 0.036f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenLargeroom        = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -2100, -1100, 2.65f, 0.33f, 0.82f, -100, 0.066f, 0f, 0f, 0f, -200, 0.049f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenHall             = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -2200, -1100, 3.45f, 0.30f, 0.82f, -100, 0.088f, 0f, 0f, 0f, -200, 0.063f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenCupboard         = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -1700, -1000, 0.56f, 0.46f, 0.91f, 100, 0.012f, 0f, 0f, 0f, 100, 0.028f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenSmallroom        = new Environment ( new float[]{ 26, 7.5f, 1f, -1000, -1900, -1000, 0.79f, 0.32f, 0.87f, 00, 0.032f, 0f, 0f, 0f, -100, 0.029f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+WoodenCourtyard        = new Environment ( new float[]{ 26, 7.5f, 0.650f, -1000, -2200, -1000, 1.79f, 0.35f, 0.79f, -500, 0.123f, 0f, 0f, 0f, -2000, 0.032f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 4705f, 99.6f, 0f, 0x3f} );
+----
+
+== 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} );
+SportSquashcourt       = new Environment ( new float[]{ 26, 7.5f, 0.750f, -1000, -1000, -200, 2.22f, 0.91f, 1.16f, -700, 0.007f, 0f, 0f, 0f, -200, 0.011f, 0f, 0f, 0f, 0.126f, 0.190f, 0.250f, 0f, -5f, 7176.9f, 211.2f, 0f, 0x20} );
+SportSmallswimmingpool = new Environment ( new float[]{ 26, 36.2f, 0.700f, -1000, -200, -100, 2.76f, 1.25f, 1.14f, -400, 0.020f, 0f, 0f, 0f, -200, 0.030f, 0f, 0f, 0f, 0.179f, 0.150f, 0.895f, 0.190f, -5f, 5000f, 250f, 0f, 0x0} );
+SportLargeswimmingpool = new Environment ( new float[]{ 26, 36.2f, 0.820f, -1000, -200, 0, 5.49f, 1.31f, 1.14f, -700, 0.039f, 0f, 0f, 0f, -600, 0.049f, 0f, 0f, 0f, 0.222f, 0.550f, 1.159f, 0.210f, -5f, 5000f, 250f, 0f, 0x0} );
+SportGymnasium         = new Environment ( new float[]{ 26, 7.5f, 0.810f, -1000, -700, -100, 3.14f, 1.06f, 1.35f, -800, 0.029f, 0f, 0f, 0f, -500, 0.045f, 0f, 0f, 0f, 0.146f, 0.140f, 0.250f, 0f, -5f, 7176.9f, 211.2f, 0f, 0x20} );
+SportFullstadium       = new Environment ( new float[]{ 26, 7.2f, 1f, -1000, -2300, -200, 5.25f, 0.17f, 0.80f, -2000, 0.188f, 0f, 0f, 0f, -1100, 0.038f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x20} );
+----
+
+== 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} );
+PipeSmall    = new Environment ( new float[]{ 26, 50.3f, 1f, -1000, -900, -1300, 5.04f, 0.10f, 0.10f, -600, 0.032f, 0f, 0f, 0f, 800, 0.015f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x3f} );
+PipeLongthin = new Environment ( new float[]{ 26, 1.6f, 0.910f, -1000, -700, -1100, 9.21f, 0.18f, 0.10f, -300, 0.010f, 0f, 0f, 0f, -300, 0.022f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x0} );
+PipeLarge    = new Environment ( new float[]{ 26, 50.3f, 1f, -1000, -900, -1300, 8.45f, 0.10f, 0.10f, -800, 0.046f, 0f, 0f, 0f, 400, 0.032f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x3f} );
+PipeResonant = new Environment ( new float[]{ 26, 1.3f, 0.910f, -1000, -700, -1100, 6.81f, 0.18f, 0.10f, -300, 0.010f, 0f, 0f, 0f, 00, 0.022f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x0} );
+----
+
+== 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} );
+Hell      = new Environment ( new float[]{ 26, 100f, 0.570f, -1000, -900, -700, 3.57f, 0.49f, 2f, -10000, 0.020f, 0f, 0f, 0f, 300, 0.030f, 0f, 0f, 0f, 0.110f, 0.040f, 2.109f, 0.520f, -5f, 5000f, 139.5f, 0f, 0x40} );
+Memory    = new Environment ( new float[]{ 26, 8f, 0.850f, -1000, -400, -900, 4.06f, 0.82f, 0.56f, -2800, 0f, 0f, 0f, 0f, 100, 0f, 0f, 0f, 0f, 0.250f, 0f, 0.474f, 0.450f, -10f, 5000f, 250f, 0f, 0x0} );
+Drugged   = new Environment ( new float[]{ 23, 1.9f, 0.500f, -1000, 0, 0, 8.39f, 1.39f, 1f, -115, 0.002f, 0f, 0f, 0f, 985, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 1f, -5f, 5000f, 250f, 0f, 0x1f} );
+Dizzy     = new Environment ( new float[]{ 24, 1.8f, 0.600f, -1000, -400, 0, 17.23f, 0.56f, 1f, -1713, 0.020f, 0f, 0f, 0f, -613, 0.030f, 0f, 0f, 0f, 0.250f, 1f, 0.810f, 0.310f, -5f, 5000f, 250f, 0f, 0x1f} );
+Psychotic = new Environment ( new float[]{ 25, 1f, 0.500f, -1000, -151, 0, 7.56f, 0.91f, 1f, -626, 0.020f, 0f, 0f, 0f, 774, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 4f, 1f, -5f, 5000f, 250f, 0f, 0x1f} );
+----
+
+== 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} );
+DrivingPitgarage       = new Environment ( new float[]{ 26, 1.9f, 0.590f, -1000, -300, -500, 1.72f, 0.93f, 0.87f, -500, 0f, 0f, 0f, 0f, 200, 0.016f, 0f, 0f, 0f, 0.250f, 0.110f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x0} );
+DrivingIncarRacer      = new Environment ( new float[]{ 26, 1.1f, 0.800f, -1000, 0, -200, 0.17f, 2f, 0.41f, 500, 0.007f, 0f, 0f, 0f, -300, 0.015f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 10268.2f, 251f, 0f, 0x20} );
+DrivingIncarSports     = new Environment ( new float[]{ 26, 1.1f, 0.800f, -1000, -400, 0, 0.17f, 0.75f, 0.41f, 0, 0.010f, 0f, 0f, 0f, -500, 0f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 10268.2f, 251f, 0f, 0x20} );
+DrivingIncarLuxury     = new Environment ( new float[]{ 26, 1.6f, 1f, -1000, -2000, -600, 0.13f, 0.41f, 0.46f, -200, 0.010f, 0f, 0f, 0f, 400, 0.010f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 10268.2f, 251f, 0f, 0x20} );
+DrivingFullgrandstand  = new Environment ( new float[]{ 26, 8.3f, 1f, -1000, -1100, -400, 3.01f, 1.37f, 1.28f, -900, 0.090f, 0f, 0f, 0f, -1500, 0.049f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 10420.2f, 250f, 0f, 0x1f} );
+DrivingEmptygrandstand = new Environment ( new float[]{ 26, 8.3f, 1f, -1000, 0, -200, 4.62f, 1.75f, 1.40f, -1363, 0.090f, 0f, 0f, 0f, -1200, 0.049f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 10420.2f, 250f, 0f, 0x1f} );
+DrivingTunnel          = new Environment ( new float[]{ 26, 3.1f, 0.810f, -1000, -800, -100, 3.42f, 0.94f, 1.31f, -300, 0.051f, 0f, 0f, 0f, -300, 0.047f, 0f, 0f, 0f, 0.214f, 0.050f, 0.250f, 0f, -5f, 5000f, 155.3f, 0f, 0x20} );
+----
+
+== 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} );
+CityStreets   = new Environment ( new float[]{ 26, 3f, 0.780f, -1000, -300, -100, 1.79f, 1.12f, 0.91f, -1100, 0.046f, 0f, 0f, 0f, -1400, 0.028f, 0f, 0f, 0f, 0.250f, 0.200f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x20} );
+CitySubway    = new Environment ( new float[]{ 26, 3f, 0.740f, -1000, -300, -100, 3.01f, 1.23f, 0.91f, -300, 0.046f, 0f, 0f, 0f, 200, 0.028f, 0f, 0f, 0f, 0.125f, 0.210f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x20} );
+CityMuseum    = new Environment ( new float[]{ 26, 80.3f, 0.820f, -1000, -1500, -1500, 3.28f, 1.40f, 0.57f, -1200, 0.039f, 0f, 0f, -0f, -100, 0.034f, 0f, 0f, 0f, 0.130f, 0.170f, 0.250f, 0f, -5f, 2854.4f, 107.5f, 0f, 0x0} );
+CityLibrary   = new Environment ( new float[]{ 26, 80.3f, 0.820f, -1000, -1100, -2100, 2.76f, 0.89f, 0.41f, -900, 0.029f, 0f, 0f, -0f, -100, 0.020f, 0f, 0f, 0f, 0.130f, 0.170f, 0.250f, 0f, -5f, 2854.4f, 107.5f, 0f, 0x0} );
+CityUnderpass = new Environment ( new float[]{ 26, 3f, 0.820f, -1000, -700, -100, 3.57f, 1.12f, 0.91f, -800, 0.059f, 0f, 0f, 0f, -100, 0.037f, 0f, 0f, 0f, 0.250f, 0.140f, 0.250f, 0f, -7f, 5000f, 250f, 0f, 0x20} );
+CityAbandoned = new Environment ( new float[]{ 26, 3f, 0.690f, -1000, -200, -100, 3.28f, 1.17f, 0.91f, -700, 0.044f, 0f, 0f, 0f, -1100, 0.024f, 0f, 0f, 0f, 0.250f, 0.200f, 0.250f, 0f, -3f, 5000f, 250f, 0f, 0x20} );
+----
+
+== 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} );
+Bathroom     = new Environment ( new float[]{ 3, 1.4f, 1f, -1000, -1200, 0, 1.49f, 0.54f, 1f, -370, 0.007f, 0f, 0f, 0f, 1030, 0.011f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Livingroom   = new Environment ( new float[]{ 4, 2.5f, 1f, -1000, -6000, 0, 0.50f, 0.10f, 1f, -1376, 0.003f, 0f, 0f, 0f, -1104, 0.004f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Paddedcell   = new Environment ( new float[]{ 1, 1.4f, 1f, -1000, -6000, 0, 0.17f, 0.10f, 1f, -1204, 0.001f, 0f, 0f, 0f, 207, 0.002f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Stoneroom    = new Environment ( new float[]{ 5, 11.6f, 1f, -1000, -300, 0, 2.31f, 0.64f, 1f, -711, 0.012f, 0f, 0f, 0f, 83, 0.017f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );----
+
+== 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} );
+Schoolroom   = new Environment ( new float[]{ 26, 1.86f, 0.690f, -1000, -400, -600, 0.98f, 0.45f, 0.18f, 300, 0.017f, 0f, 0f, 0f, 300, 0.015f, 0f, 0f, 0f, 0.095f, 0.140f, 0.250f, 0f, -5f, 7176.9f, 211.2f, 0f, 0x20} );
+Practiseroom = new Environment ( new float[]{ 26, 1.86f, 0.870f, -1000, -800, -600, 1.12f, 0.56f, 0.18f, 200, 0.010f, 0f, 0f, 0f, 300, 0.011f, 0f, 0f, 0f, 0.095f, 0.140f, 0.250f, 0f, -5f, 7176.9f, 211.2f, 0f, 0x20} );
+Outhouse     = new Environment ( new float[]{ 26, 80.3f, 0.820f, -1000, -1900, -1600, 1.38f, 0.38f, 0.35f, -100, 0.024f, 0f, 0f, -0f, -400, 0.044f, 0f, 0f, 0f, 0.121f, 0.170f, 0.250f, 0f, -5f, 2854.4f, 107.5f, 0f, 0x0} );
+Caravan      = new Environment ( new float[]{ 26, 8.3f, 1f, -1000, -2100, -1800, 0.43f, 1.50f, 1f, 0, 0.012f, 0f, 0f, 0f, 600, 0.012f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x1f} );
+Dustyroom    = new Environment ( new float[]{ 26, 1.8f, 0.560f, -1000, -200, -300, 1.79f, 0.38f, 0.21f, -600, 0.002f, 0f, 0f, 0f, 200, 0.006f, 0f, 0f, 0f, 0.202f, 0.050f, 0.250f, 0f, -10f, 13046f, 163.3f, 0f, 0x20} );
+Chapel       = new Environment ( new float[]{ 26, 19.6f, 0.840f, -1000, -500, 0, 4.62f, 0.64f, 1.23f, -700, 0.032f, 0f, 0f, 0f, -200, 0.049f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0.110f, -5f, 5000f, 250f, 0f, 0x3f} );
+----
+
+== 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} );
+Concerthall    = new Environment ( new float[]{ 7, 19.6f, 1f, -1000, -500, 0, 3.92f, 0.70f, 1f, -1230, 0.020f, 0f, 0f, 0f, -02, 0.029f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Cave           = new Environment ( new float[]{ 8, 14.6f, 1f, -1000, 0, 0, 2.91f, 1.30f, 1f, -602, 0.015f, 0f, 0f, 0f, -302, 0.022f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x1f} );
+Arena          = new Environment ( new float[]{ 9, 36.2f, 1f, -1000, -698, 0, 7.24f, 0.33f, 1f, -1166, 0.020f, 0f, 0f, 0f, 16, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Hangar         = new Environment ( new float[]{ 10, 50.3f, 1f, -1000, -1000, 0, 10.05f, 0.23f, 1f, -602, 0.020f, 0f, 0f, 0f, 198, 0.030f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+DomeTomb       = new Environment ( new float[]{ 26, 51.8f, 0.790f, -1000, -900, -1300, 4.18f, 0.21f, 0.10f, -825, 0.030f, 0f, 0f, 0f, 450, 0.022f, 0f, 0f, 0f, 0.177f, 0.190f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x0} );
+DomeSaintPauls = new Environment ( new float[]{ 26, 50.3f, 0.870f, -1000, -900, -1300, 10.48f, 0.19f, 0.10f, -1500, 0.090f, 0f, 0f, 0f, 200, 0.042f, 0f, 0f, 0f, 0.250f, 0.120f, 0.250f, 0f, -5f, 2854.4f, 20f, 0f, 0x3f} );
+----
+
+== 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} );
+Hallway          = new Environment ( new float[]{ 12, 1.8f, 1f, -1000, -300, 0, 1.49f, 0.59f, 1f, -1219, 0.007f, 0f, 0f, 0f, 441, 0.011f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Stonecorridor    = new Environment ( new float[]{ 13, 13.5f, 1f, -1000, -237, 0, 2.70f, 0.79f, 1f, -1214, 0.013f, 0f, 0f, 0f, 395, 0.020f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Alley            = new Environment ( new float[]{ 14, 7.5f, 0.300f, -1000, -270, 0, 1.49f, 0.86f, 1f, -1204, 0.007f, 0f, 0f, 0f, -4, 0.011f, 0f, 0f, 0f, 0.125f, 0.950f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+----
+
+== 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} );
+Plain         = new Environment ( new float[]{ 19, 42.5f, 0.210f, -1000, -2000, 0, 1.49f, 0.50f, 1f, -2466, 0.179f, 0f, 0f, 0f, -1926, 0.100f, 0f, 0f, 0f, 0.250f, 1f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Rollingplains = new Environment ( new float[]{ 26, 80.3f, 0f, -1000, -3900, -400, 2.13f, 0.21f, 0.46f, -1500, 0.300f, 0f, 0f, -0f, -700, 0.019f, 0f, 0f, 0f, 0.250f, 1f, 0.250f, 0f, -5f, 4399.1f, 242.9f, 0f, 0x0} );
+Deepcanyon    = new Environment ( new float[]{ 26, 80.3f, 0.740f, -1000, -1500, -400, 3.89f, 0.21f, 0.46f, -1000, 0.223f, 0f, 0f, -0f, -900, 0.019f, 0f, 0f, 0f, 0.250f, 1f, 0.250f, 0f, -5f, 4399.1f, 242.9f, 0f, 0x0} );
+Creek         = new Environment ( new float[]{ 26, 80.3f, 0.350f, -1000, -1500, -600, 2.13f, 0.21f, 0.46f, -800, 0.115f, 0f, 0f, -0f, -1400, 0.031f, 0f, 0f, 0f, 0.218f, 0.340f, 0.250f, 0f, -5f, 4399.1f, 242.9f, 0f, 0x0} );
+Valley        = new Environment ( new float[]{ 26, 80.3f, 0.280f, -1000, -3100, -1600, 2.88f, 0.26f, 0.35f, -1700, 0.263f, 0f, 0f, -0f, -800, 0.100f, 0f, 0f, 0f, 0.250f, 0.340f, 0.250f, 0f, -5f, 2854.4f, 107.5f, 0f, 0x0} );
+Forest        = new Environment ( new float[]{ 15, 38f, 0.300f, -1000, -3300, 0, 1.49f, 0.54f, 1f, -2560, 0.162f, 0f, 0f, 0f, -229, 0.088f, 0f, 0f, 0f, 0.125f, 1f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Mountains     = new Environment ( new float[]{ 17, 100f, 0.270f, -1000, -2500, 0, 1.49f, 0.21f, 1f, -2780, 0.300f, 0f, 0f, 0f, -1434, 0.100f, 0f, 0f, 0f, 0.250f, 1f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x1f} );
+Quarry        = new Environment ( new float[]{ 18, 17.5f, 1f, -1000, -1000, 0, 1.49f, 0.83f, 1f, -10000, 0.061f, 0f, 0f, 0f, 500, 0.025f, 0f, 0f, 0f, 0.125f, 0.700f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x3f} );
+Parkinglot    = new Environment ( new float[]{ 20, 8.3f, 1f, -1000, 0, 0, 1.65f, 1.50f, 1f, -1363, 0.008f, 0f, 0f, 0f, -1153, 0.012f, 0f, 0f, 0f, 0.250f, 0f, 0.250f, 0f, -5f, 5000f, 250f, 0f, 0x1f} );
+----
+
+== 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} );
+Smallwaterroom = new Environment ( new float[]{ 26, 36.2f, 0.700f, -1000, -698, 0, 1.51f, 1.25f, 1.14f, -100, 0.020f, 0f, 0f, 0f, 300, 0.030f, 0f, 0f, 0f, 0.179f, 0.150f, 0.895f, 0.190f, -7f, 5000f, 250f, 0f, 0x0} );
+----

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

@@ -0,0 +1,255 @@
+
+
+= Bloom and Glow
+
+Bloom is a popular shader effect in 3D games industry. It usually consist in displaying a glowing halo around light sources or bright areas of a scene.
+In practice, the bright areas are extracted from the rendered scene, blurred and finally added up to the render.
+
+
+Those images gives an idea of what bloom does. The left image has no bloom effect, the right image does. +
+
+image:jme3/advanced/nobloomsky.png[No bloom,with="",height=""]image:jme3/advanced/blomsky.png[Bloom,with="",height=""]
+
+
+
+= Bloom Usage
+
+.  Create a FilterPostProcessor
+.  Create a BloomFilter
+.  Add the filter to the processor
+.  Add the processor to the viewPort
+
+[source,java]
+----
+ FilterPostProcessor fpp=new FilterPostProcessor(assetManager);
+ BloomFilter bloom=new BloomFilter();
+ fpp.addFilter(bloom);
+ viewPort.addProcessor(fpp);
+----
+Here are the parameters that you can tweak :
+
+[cols="4", options="header"]
+|===
+
+<a| Parameter           
+<a| Method                
+a| Default 
+a| Description 
+
+<a| blur scale              
+a| `setBlurScale(float)` 
+<a|1.5f  
+a| the scale of the bloom effect, but be careful, high values does artifacts 
+
+<a| exposure Power              
+a| `setExposurePower(float)` 
+<a|5.0f  
+a| the glowing channel color is raised to the value power 
+
+<a| exposure cut-off              
+a| `setExposureCutOff(float)` 
+<a|0.0f  
+a| the threshold of color to bloom during extraction 
+
+<a| bloom intensity              
+a| `setBloomIntensity(float)` 
+<a|2.0f  
+a| the resulting bloom value is multiplied by this intensity 
+
+|===
+
+You'll probably need to adjust those parameters depending on your scene.
+
+
+
+= Bloom with a glow map
+
+Sometimes, you want to have more control over what glows and does not glow. 
+The bloom filter supports a glow map or a glow color.
+
+
+
+===== Creating a glow-map
+
+Let's take the hover tank example bundled with JME3 test data.+
+
+Here you can see the diffuse map of the tank, and the associated glow map that only contains the parts of the texture that will glow and their glowing color: +
+
+image:jme3/advanced/tank_diffuse_ss.png[Tank diffuse map,with="",height=""]
+image:jme3/advanced/tank_glow_map_ss.png[Tank glow map,with="",height=""]
+
+
+Glow maps work with Lighting.j3md, Particles.j3md and SolidColor.j3md material definitions.
+The tank material looks like this : 
+
+
+[source]
+----
+Material My Material : Common/MatDefs/Light/Lighting.j3md {
+     MaterialParameters {
+        SpecularMap : Models/HoverTank/tank_specular.png
+        Shininess : 8
+        NormalMap : Models/HoverTank/tank_normals.png
+        DiffuseMap : Models/HoverTank/tank_diffuse.png
+        GlowMap : Models/HoverTank/tank_glow_map_highres.png
+        UseMaterialColors : true
+        Ambient  : 0.0 0.0 0.0 1.0
+        Diffuse  : 1.0 1.0 1.0 1.0
+        Specular : 1.0 1.0 1.0 1.0
+     }
+}
+----
+The glow map is defined here : *GlowMap : Models/HoverTank/tank_glow_map_highres.png*
+
+
+
+===== Usage
+
+.  Create a FilterPostProcessor
+.  Create a BloomFilter with the GlowMode.Objects parameter
+.  Add the filter to the processor
+.  Add the processor to the viewPort
+
+[source]
+----
+  FilterPostProcessor fpp=new FilterPostProcessor(assetManager);
+  BloomFilter bf=new BloomFilter(BloomFilter.GlowMode.Objects);
+  fpp.addFilter(bf);
+  viewPort.addProcessor(fpp);
+----
+Here is the result : +
+
+image:jme3/advanced/tanlglow1.png[Glowing hover tank,with="",height=""]
+
+
+
+= Bloom with a glow color
+
+Sometimes you need an entire object to glow, not just parts of it.
+In this case you'll need to use the glow color parameter.
+
+
+
+===== Usage
+
+.  Create a material for your object and set the GlowColor parameter
+.  Create a FilterPostProcessor
+.  Create a BloomFilter with the GlowMode.Objects parameter
+.  Add the filter to the processor
+.  Add the processor to the viewPort
+
+[source]
+----
+    Material mat = new Material(getAssetManager(), "Common/MatDefs/Misc/SolidColor.j3md");
+    mat.setColor("Color", ColorRGBA.Green);
+    mat.setColor("GlowColor", ColorRGBA.Green);
+    fpp=new FilterPostProcessor(assetManager);
+    bloom= new BloomFilter(BloomFilter.GlowMode.Objects);        
+    fpp.addFilter(bloom);
+    viewPort.addProcessor(fpp);
+----
+Here is the result on Oto's plasma ball (before and after) : +
+
+
+image::jme3/advanced/otonobloom.png[Oto's plasma ball is just a big pea,with="400",height="",align="left"]
+
+
+image::jme3/advanced/otoglow.png[Oto's plasma ball radiates incredible power!!!,with="400",height="",align="left"]
+
+
+
+
+= Hints and tricks
+
+
+===== Increasing the blur range and reducing fps cost
+
+The glow render is sampled on a texture that has the same dimensions as the viewport.
+You can reduce the size of the bloom sampling just by using the setDownSamplingFactor method like this : +
+
+
+
+[source,java]
+----
+ BloomFilter bloom=new BloomFilter();
+ bloom.setDownSamplingFactor(2.0f); 
+----
+In this example the sampling size is divided by 4 (width/2,height/2), resulting in less work to blur the scene.
+The resulting texture is then up sampled to the screen size using hardware bilinear filtering. this results in a wider blur range.
+
+
+
+===== Using classic bloom combined with a glow map
+
+let's say you want a global bloom on your scene, but you have also a glowing object on it.
+You can use only one bloom filter for both effects like that
+
+
+[source,java]
+----
+BloomFilter bloom=new BloomFilter(BloomFilter.GlowMode.SceneAndObjects);
+----
+However, note that both effects will share the same values of attribute, and sometimes, it won't be what you need.
+
+
+
+===== Making your home brewed material definition support Glow
+
+Let's say you have made a custom material on your own, and that you want it to support glow maps and glow color.
+In your material definition you need to add those lines in the MaterialParameters section :
+
+
+[source]
+----
+ MaterialParameters {
+        
+        ....
+
+        // Texture of the glowing parts of the material
+        Texture2D GlowMap
+        // The glow color of the object
+        Color GlowColor
+    }
+----
+Then add the following technique : 
+
+
+[source]
+----
+    Technique Glow {
+
+        LightMode SinglePass
+
+        VertexShader GLSL100:   Common/MatDefs/Misc/SimpleTextured.vert
+        FragmentShader GLSL100: Common/MatDefs/Light/Glow.frag
+
+        WorldParameters {
+            WorldViewProjectionMatrix
+        }
+
+        Defines {
+            HAS_GLOWMAP : GlowMap
+            HAS_GLOWCOLOR : GlowColor
+        }
+    }
+----
+Then you can use this material with the BloomFilter
+
+
+
+===== Make a glowing object stop to glow
+
+If you are using a glow map, remove the texture from the material.
+
+
+[source]
+----
+material.clearTextureParam("GlowMap");
+----
+If you are using a glow color, set it to black
+
+
+[source]
+----
+material.setColor("GlowColor",ColorRGBA.Black);
+----<tags><tag target="documentation" /><tag target="effect" /><tag target="light" /></tags>

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

@@ -0,0 +1,162 @@
+
+
+= How to Build the jNavigation Recast Bindings
+
+jNavigation is Java jME port for Recast Navigation written in C++. The project has two parts:
+
+
+.  link:https://github.com/QuietOne/jNavigation-native[jNavigationNative] contains Recast Navigation library and C++ wrapper for java
+.  link:https://github.com/QuietOne/jNavigation[jNavigation] is Java project that uses jNavigationNative and is the project that the end user will use
+
+If there is need for updating Recast Navigation from native side, there are two kinds of updating bindings:
+
+
+.  only updating methods as the Recast made more efficient or more precise
+.  adding new methods for Recast use
+
+
+== Updating methods
+
+Only updating methods are easy. The requirements needed:
+
+
+*  C++ compiler
+
+The jNavigationNative that has following folders and files (it has more, but these are the most important for now):
+
+
+*  Recast
+**  Include
+**  Source
+
+*  README.md
+*  Recast_wrap.cxx - Java - C++ wrapper
+
+Updating the methods is only the matter of putting all headers from Recast Navigation to Include folder, source to Source folders, and then building the project.
+
+
+As author of this project used the NetBeans 7.4 for building the project, the following instruction is included, if the building from terminal doesn't work.
+
+
+.  Setting link:https://netbeans.org/kb/docs/cnd/beginning-jni-linux.html[ parameters for NetBeans compiler]
+.  Remove all headers from Header Files
+.  Remove all source files *EXCEPT Recast_wrap.cxx* from Source Files
+.  Right click on Header files, select `Add Existing Item…` or `Add Existing Items from Folders…` and select needed headers
+.  Right click on Source files, select `Add Existing Item…` or `Add Existing Items from Folders…` and select needed source files
+.  Build
+.  Add built project to jNavigation project
+.  Build jNavigation project
+
+
+=== Adding new methods from native side
+
+This is more complicated process and it includes the all work done in NetBeans mentioned in previous section. After that, there are two ways to add new function:
+
+
+*  manually adding code to wrapper
+*  creating new wrapper with link:http://swig.org/[SWIG]
+
+
+==== Manually adding code to wrapper
+
+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_) {
+ ...
+}
+----
+The Recast_wrap.cxx uses SWIG wrapper so for declaring method in wrapper you must first use the keyword `SWIGEXPORT` then returning type (for more information on returning types see link:http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/types.html[link]), then again keyword `JNICALL` and then as the name of method `Java_com_jme3_ai_navigation_utils_RecastJNI_` + `name of class` + `name of method`, after that, there goes list of parameters needed for the function (for more information see link:http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html[link]). In body of method write how the function should be used.
+
+
+After adding method to wrapper, compile project and add it to jNavigation.
+In jNavigation project in class `com.jme3.ai.navigation.utils.RecastJNI.java` add native method, and after that add in class from which you would like to use this method to call this native method. It seems a little bit more complicated than it should be, but this also for support for updating native side with SWIG.
+
+
+
+==== Creating new wrapper with SWIG
+
+In some temporary folder add all headers. It shouldn't contain any subfolders.
+
+
+The following script was used for generating wrapper:
+
+
+[source]
+----
+%module Recast
+%include "carrays.i"
+%array_class(double, DoubleArray);
+%array_class(float, FloatArray);
+%array_class(int, IntArray);
+%array_class(unsigned char, UCharArray);
+%array_class(unsigned short, UShortArray);
+%array_class(unsigned int, UIntArray);
+%array_class(long, LongArray);
+%array_class(bool, BooleanArray)
+
+%{
+#include "DetourAlloc.h"
+#include "DetourAssert.h"
+#include "DetourCommon.h"
+#include "DetourCrowd.h"
+#include "DetourLocalBoundary.h"
+#include "DetourMath.h"
+#include "DetourNavMesh.h"
+#include "DetourNavMeshBuilder.h"
+#include "DetourNavMeshQuery.h"
+#include "DetourNode.h"
+#include "DetourObstacleAvoidance.h"
+#include "DetourPathCorridor.h"
+#include "DetourPathQueue.h"
+#include "DetourProximityGrid.h"
+#include "DetourStatus.h"
+#include "DetourTileCache.h"
+#include "DetourTileCacheBuilder.h"
+#include "Recast.h"
+#include "RecastAlloc.h"
+#include "RecastAssert.h"
+%}
+
+/* Let's just grab the original header file here */
+%include "DetourAlloc.h"
+%include "DetourAssert.h"
+%include "DetourCommon.h"
+%include "DetourCrowd.h"
+%include "DetourLocalBoundary.h"
+%include "DetourMath.h"
+%include "DetourNavMesh.h"
+%include "DetourNavMeshBuilder.h"
+%include "DetourNavMeshQuery.h"
+%include "DetourNode.h"
+%include "DetourObstacleAvoidance.h"
+%include "DetourPathCorridor.h"
+%include "DetourPathQueue.h"
+%include "DetourProximityGrid.h"
+%include "DetourStatus.h"
+%include "DetourTileCache.h"
+%include "DetourTileCacheBuilder.h"
+%include "Recast.h"
+%include "RecastAlloc.h"
+%include "RecastAssert.h"
+
+%pragma(java) jniclasscode=%{
+  static {
+    System.load("Recast");
+  }
+%}
+----
+If there are more headers at some moment, include them in both places.
+
+
+.  Save script as Recast.i into temp folder with rest of the headers
+.  Install SWIG if not already
+.  Open terminal and go to folder where the script is
+.  Execute command `swig -c++ -java Recast.i`
+.  Now SWIG will generate Java classes and new Recast_wrap.cxx
+.  Recast_wrap.cxx put in jNavigationNative with new headers and source files, as previously mentioned
+.  Build that project
+.  For jNavigation side, put only new methods in RecastJNI, and use where they are being used. For that you can see in Java class that are build with SWIG.
+.  If method uses some explicit SWIG type, try to use some method for converting it into jME type, or similar. You can probably find something in package `com.jme3.ai.navigation.utils`

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

@@ -0,0 +1,47 @@
+
+
+= Multithreading Bullet Physics in jme3
+
+
+== Introduction
+
+Since bullet is not (yet) multithreaded or GPU accelerated, the jME3 implementation allows to run each physics space on a separate thread that is executed in parallel to rendering.
+
+
+
+== How is it handled in jme3 and bullet?
+
+A SimpleApplication with a BulletAppState allows setting the threading type via 
+
+
+[source]
+----setThreadingType(ThreadingType type);----
+ where ThreadingType can be either SEQUENTIAL or PARALLEL. By default, it's SEQUENTIAL.
+
+
+You can activate PARALLEL threading in the simpleInitApp() method:
+
+
+[source,java]
+----bulletAppState = new BulletAppState();
+bulletAppState.setThreadingType(BulletAppState.ThreadingType.PARALLEL);
+stateManager.attach(bulletAppState);----
+Now the physics update happens in parallel to render(), that is, after the user's changes in the update() call have been applied. During update() the physics update loop pauses. This way the loop logic is still maintained: the user can set and change values in physics and scenegraph objects before render() and physicsUpdate() are called in parallel. This allows you to use physics methods in update() as if it was single-threaded.
+
+[cols="2", options="header"]
+|===
+
+a|PARALLEL
+a|SEQUENTIAL
+
+a|1. update(), 2. render() and physics update().
+<a|1. update(), 2. render(), 3. physics update().  
+
+a|Physics Debug View is rendered inaccurately (out of sync)
+a|Physics Debug View is rendered accurately.
+
+|===
+
+
+
+<tags><tag target="documentation" /><tag target="physics" /><tag target="threading" /></tags>

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

@@ -0,0 +1,36 @@
+
+
+= Bullet Physics Pitfalls
+
+Bullet physics is not without its problems. Unfortunately, many of those are outside of the control of the jMonkeyEngine Core Team and thus cannot be fixed.
+
+
+
+=== Sweep Test Issues
+
+.  When using link:http://jmonkeyengine.org/javadoc/com/jme3/bullet/PhysicsSpace.html#sweepTest(com.jme3.bullet.collision.shapes.CollisionShape, com.jme3.math.Transform, com.jme3.math.Transform)[PhysicsSpace.sweepTest()], ensure that the distance between the transforms is at least 0.4wu or greater.
+.  Note that the sweep will not detect collisions if it done inside of a collision shape. It must be on the edge of a collision shape to detect any collisions.
+
+
+=== Ghost Control AABB Collision only
+
+As the javadoc for link:http://jmonkeyengine.org/javadoc/com/jme3/bullet/objects/PhysicsGhostObject.html[PhysicsObjectControl] says, the ghost object collision detection uses AABB (Axis-aligned bounding box) collision only, regardless of the collision shape it has been assigned.
+
+
+*Workaround:*+
+
+Please use PhysicsSpace.sweepTest() instead, or kinematic physics objects with link:http://jmonkeyengine.org/javadoc/com/jme3/bullet/PhysicsSpace.html#addCollisionListener(com.jme3.bullet.collision.PhysicsCollisionListener)[collision listeners].
+
+
+
+=== Rigid bodies fall through ground
+
+This usually happens if the ground physics object has large triangles or consists of a large BoxCollisionShape. 
+
+
+*Workaround:*+
+
+
+
+*  For meshes with large triangles - Subdivide the mesh in a model editor such as Blender.
+*  For large boxes - seperate into smaller boxes or use a MeshCollisionShape for terrain instead of BoxCollisionShape.

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

@@ -0,0 +1,163 @@
+
+
+= The jME3 Camera
+
+Note that by default, the mouse pointer is invisible, and the mouse is set up to control the camera rotation.
+
+
+
+== Default Camera
+
+The default com.jme3.renderer.Camera object is `cam` in com.jme3.app.Application.
+
+
+The camera object is created with the following defaults:
+
+
+*  Width and height are set to the current Application's settings.getWidth() and settings.getHeight() values. 
+*  Frustum Perspective:
+**  Frame of view angle of 45° along the Y axis
+**  Aspect ratio of width divided by height
+**  Near view plane of 1 wu
+**  Far view plane of 1000 wu
+
+*  Start location at (0f, 0f, 10f).
+*  Start direction is looking at the origin.
+[cols="2", options="header"]
+|===
+
+a|Method
+a|Usage
+
+a|cam.getLocation(), setLocation()
+a|The camera position
+
+a|cam.getRotation(), setRotation()
+a|The camera rotation
+
+a|cam.getLeft(), setLeft()
+a|The left axis of the camera
+
+a|cam.getUp(), setUp()
+a|The up axis of the camera, usually Vector3f(0,1,0)
+
+a|cam.getDirection()
+a|The vector the camera is facing
+
+a|cam.getAxes(), setAxes(left,up,dir)
+a|One accessor for the three properties left/up/direction.
+
+a|cam.getFrame(), setFrame(loc,left,up,dir)
+a|One accessor for the four properties location/left/up/direction.
+
+a|cam.resize(width, height, fixAspect)
+a|Resize an existing camera object while keeping all other settings. Set fixAspect to true to adjust the aspect ratio (?)
+
+a|cam.setFrustum( near, far, left, right, top, bottom )
+a|The frustum is defined by the near/far plane, left/right plane, top/bottom plane (all distances as float values)
+
+a|cam.setFrustumPerspective( fovY, aspect ratio, near, far)
+a|The frustum is defined by view angle along the Y axis (in degrees), aspect ratio, and the near/far plane.
+
+a|cam.lookAt(target,up)
+a|Turn the camera to look at Coordinate target, and rotate it around the up axis.
+
+a|cam.setParallelProjection(false)
+a|Normal perspective
+
+a|cam.setParallelProjection(true)
+a|Parallel projection perspective
+
+a|cam.getScreenCoordinates()
+a|?
+
+|===
+
+*Tip:* After you change view port, frustum, or frame, call `cam.update();`
+
+
+
+== FlyBy Camera
+
+The `flyCam` class field gives you access to an AppState that extends the default camera in `com.jme3.app.SimpleApplication` with more features. The input manager of the `com.jme3.input.FlyByCamera` AppState is preconfigured to respond to the WASD keys for walking forwards and backwards, and strafing to the sides; move the mouse to rotate the camera (“Mouse Look), scroll the mouse wheel for zooming in or out. The QZ keys raise or lower the camera vertically.
+
+
+[source]
+----
+Q  W             up   forw
+A  S  D    -->  left  back  right 
+Z               down  
+----[cols="2", options="header"]
+|===
+
+a|Method
+a|Usage
+
+a|flyCam.setEnabled(true);
+a|Activate the flyby cam
+
+a|flyCam.setMoveSpeed(10);
+a|Control the move speed
+
+a|flyCam.setRotationSpeed(10);
+a|Control the rotation speed
+
+a|flyCam.setDragToRotate(true)
+a|Forces the player to keep mouse button pressed to rotate camera, typically used for Applets. If false (default), all mouse movement will be captured and interpreted as rotations.
+
+|===
+
+The FlyByCamera is active by default, but you can change all these defaults for your game.
+
+
+
+== Chase Camera
+
+jME3 also supports an optional Chase Cam that can follow a moving target Spatial (`com.jme3.input.ChaseCamera`). When you use the chase cam, the player clicks and hold the mouse button to rotate the camera around the camera target. You can use a chase cam if you need the mouse pointer visible in your game.
+
+
+[source,java]
+----
+flyCam.setEnabled(false);
+ChaseCamera chaseCam = new ChaseCamera(cam, target, inputManager);
+----[cols="2", options="header"]
+|===
+
+a|Method
+a|Usage
+
+a|chaseCam.setSmoothMotion(true);
+a|Interpolates a smoother acceleration/deceleration when the camera moves.
+
+a|chaseCam.setChasingSensitivity(5f)
+a|The lower the chasing sensitivity, the slower the camera will follow the target when it moves.
+
+a|chaseCam.setTrailingSensitivity(0.5f)
+a|The lower the traling sensitivity, the slower the camera will begin to go after the target when it moves. Default is 0.5;
+
+a|chaseCam.setRotationSensitivity(5f)
+a|The lower the sensitivity, the slower the camera will rotate around the target when the mosue is dragged. Default is 5.
+
+a|chaseCam.setTrailingRotationInertia(0.1f)
+a|This prevents the camera to stop too abruptly when the target stops rotating before the camera has reached the target's trailing position. Default is 0.1f.
+
+a|chaseCam.setDefaultDistance(40);
+a|The default distance to the target at the start of the application.
+
+a|chaseCam.setMaxDistance(40);
+a|The maximum zoom distance. Default is 40f.
+
+a|chaseCam.setMinDistance(1);
+a|The minimum zoom distance. Default is 1f.
+
+a|chaseCam.setMinVerticalRotation(-FastMath.PI/2);
+a|The minimal vertical rotation angle of the camera around the target. Default is 0.
+
+a|chaseCam.setDefaultVerticalRotation(-FastMath.PI/2);
+a|The default vertical rotation angle of the camera around the target at the start of the application.
+
+a|chaseCam.setDefaultHorizontalRotation(-FastMath.PI/2);
+a|The default horizontal rotation angle of the camera around the target at the start of the application.
+
+|===
+<tags><tag target="camera" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,583 @@
+
+
+= Capture Audio/Video to a File
+
+So you've made your cool new JMonkeyEngine3 game and you want to
+create a demo video to show off your hard work. Or maybe you want to
+make a cutscene for your game using the physics and characters in the
+game itself.  Screen capturing is the most straightforward way to do
+this, but it can slow down your game and produce low-quality video and
+audio as a result. A better way is to record video and audio directly
+from the game while it is running using VideoRecorderAppState.
+
+
+
+<<jme3/advanced/cinematics#,Cinematics>>
+
+
+
+
+== Simple Way
+
+First off, if all you need is to record video at 30fps with no sound, then look
+no further than jMonkeyEngine 3's built in `VideoRecorderAppState`
+class.
+
+
+Add the following code to your `simpleInitApp()` method. 
+
+
+[source,java]
+----
+stateManager.attach(new VideoRecorderAppState()); //start recording
+----
+The game will run slow, but the recording will be in high-quality and
+normal speed. Recording starts when the state is
+attached, and ends when the application quits or the state is detached.
+
+
+The video files will be stored in your *user home directory*. 
+If you want to save to another path, specify a File object in the
+VideoRecorderAppState constructor. 
+
+
+That's all!
+
+
+
+== Advanced Way
+
+
+
+
+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
+solution for doing this already made for you here:
+
+
+link:http://www.aurellem.com/releases/jmeCapture-latest.zip[http://www.aurellem.com/releases/jmeCapture-latest.zip]
+
+
+link:http://www.aurellem.com/releases/jmeCapture-latest.tar.bz2[http://www.aurellem.com/releases/jmeCapture-latest.tar.bz2]
+
+
+Download the archive in your preferred format, extract,
+add the jars to your project, and you are ready to go.
+
+
+The javadoc is here:
+link:http://www.aurellem.com/jmeCapture/docs/[http://www.aurellem.com/jmeCapture/docs/]
+
+
+To capture video and audio you use the
+`com.aurellem.capture.Capture` class, which has two methods,
+`captureAudio()` and `captureVideo()`, and the
+`com.aurellem.capture.IsoTimer` class, which sets the audio and
+video framerate.
+
+
+The steps are:
+
+
+[source,java]
+----
+yourApp.setTimer(new IsoTimer(desiredFramesPerSecond));
+----
+This causes jMonkeyEngine to take as much time as it needs to fully
+calculate every frame of the video and audio.  You will see your game
+speed up and slow down depending on how computationally demanding your
+game is, but the final recorded audio and video will be perfectly
+sychronized and will run at exactly the fps which you specified.
+
+
+[source,java]
+----
+captureVideo(yourApp, targetVideoFile);
+captureAudio(yourApp, targetAudioFile);
+----
+These will cause the app to record audio and video when it is run.
+Audio and video will stop being recorded when the app stops. Your
+audio will be recorded as a 44,100 Hz linear PCM wav file, while the
+video will be recorded according to the following rules:
+
+
+1.) (Preferred) If you supply an empty directory as the file, then
+the video will be saved as a sequence of .png files, one file per
+frame.  The files start at 0000000.png and increment from there.
+You can then combine the frames into your preferred
+container/codec. If the directory is not empty, then writing
+video frames to it will fail, and nothing will be written.
+
+
+2.) If the filename ends in “.avi then the frames will be encoded as
+a RAW stream inside an AVI 1.0 container.  The resulting file
+will be quite large and you will probably want to re-encode it to
+your preferred container/codec format.  Be advised that some
+video payers cannot process AVI with a RAW stream, and that AVI
+1.0 files generated by this method that exceed 2.0GB are invalid
+according to the AVI 1.0 +++<abbr title="specification">spec</abbr>+++ (but many programs can still deal
+with them.)  Thanks to 
+link:http://www.randelshofer.ch/blog/2008/08/writing-avi-videos-in-pure-java/[Werner Randelshofer]
+for his excellent work which made the AVI file writer option possible.
+
+
+3.) Any non-directory file ending in anything other than “.avi will
+be processed through Xuggle.  Xuggle provides the option to use
+many codecs/containers, but you will have to install it on your
+system yourself in order to use this option. Please visit
+link:http://www.xuggle.com/[http://www.xuggle.com/] to learn how to do this.
+
+
+Note that you will not hear any sound if you choose to record sound to
+a file.
+
+
+
+=== Basic Example
+
+Here is a complete example showing how to capture both audio and video
+from one of jMonkeyEngine3's advanced demo applications.
+
+
+[source,java]
+----
+import java.io.File;
+import java.io.IOException;
+
+import jme3test.water.TestPostWater;
+
+import com.aurellem.capture.Capture;
+import com.aurellem.capture.IsoTimer;
+import com.jme3.app.SimpleApplication;
+
+
+/**
+ * Demonstrates how to use basic Audio/Video capture with a
+ * jMonkeyEngine application. You can use these techniques to make
+ * high quality cutscenes or demo videos, even on very slow laptops.
+ * 
+ * @author Robert McIntyre
+ */
+
+public class Basic {
+	
+    public static void main(String[] ignore) throws IOException{
+	File video = File.createTempFile("JME-water-video", ".avi");
+	File audio = File.createTempFile("JME-water-audio", ".wav");
+		
+	SimpleApplication app = new TestPostWater();
+	app.setTimer(new IsoTimer(60));
+	app.setShowSettings(false);
+		
+	Capture.captureVideo(app, video);
+	Capture.captureAudio(app, audio);
+		
+	app.start();
+		
+	System.out.println(video.getCanonicalPath());
+	System.out.println(audio.getCanonicalPath());
+    }
+}
+----
+
+=== How it works
+
+A standard JME3 application that extends `SimpleApplication` or
+`Application` tries as hard as it can to keep in sync with
+_user-time_.  If a ball is rolling at 1 game-mile per game-hour in the
+game, and you wait for one user-hour as measured by the clock on your
+wall, then the ball should have traveled exactly one game-mile. In
+order to keep sync with the real world, the game throttles its physics
+engine and graphics display.  If the computations involved in running
+the game are too intense, then the game will first skip frames, then
+sacrifice physics accuracy.  If there are particuraly demanding
+computations, then you may only get 1 fps, and the ball may tunnel
+through the floor or obstacles due to inaccurate physics simulation,
+but after the end of one user-hour, that ball will have traveled one
+game-mile.
+
+
+When we're recording video, we don't care if the game-time syncs with
+user-time, but instead whether the time in the recorded video
+(video-time) syncs with user-time. To continue the analogy, if we
+recorded the ball rolling at 1 game-mile per game-hour and watched the
+video later, we would want to see 30 fps video of the ball rolling at
+1 video-mile per _user-hour_. It doesn't matter how much user-time it
+took to simulate that hour of game-time to make the high-quality
+recording.
+
+
+The IsoTimer ignores real-time and always reports that the same amount
+of time has passed every time it is called. That way, one can put code
+to write each video/audio frame to a file without worrying about that
+code itself slowing down the game to the point where the recording
+would be useless.
+
+
+
+=== Advanced Example
+
+The package from aurellem.com was made for AI research and can do more
+than just record a single stream of audio and video. You can use it
+to:
+
+
+1.) Create multiple independent listeners that each hear the world
+from their own perspective.
+
+
+2.) Process the sound data in any way you wish.
+
+
+3.) Do the same for visual data.
+
+
+Here is a more advanced example, which can also be found along with
+other examples in the jmeCapture.jar file included in the
+distribution.
+
+
+[source,java]
+----
+package com.aurellem.capture.examples;
+
+import java.io.File;
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.ByteBuffer;
+
+import javax.sound.sampled.AudioFormat;
+
+import org.tritonus.share.sampled.FloatSampleTools;
+
+import com.aurellem.capture.AurellemSystemDelegate;
+import com.aurellem.capture.Capture;
+import com.aurellem.capture.IsoTimer;
+import com.aurellem.capture.audio.CompositeSoundProcessor;
+import com.aurellem.capture.audio.MultiListener;
+import com.aurellem.capture.audio.SoundProcessor;
+import com.aurellem.capture.audio.WaveFileWriter;
+import com.jme3.app.SimpleApplication;
+import com.jme3.audio.AudioNode;
+import com.jme3.audio.Listener;
+import com.jme3.cinematic.MotionPath;
+import com.jme3.cinematic.events.AbstractCinematicEvent;
+import com.jme3.cinematic.events.MotionTrack;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.FastMath;
+import com.jme3.math.Quaternion;
+import com.jme3.math.Vector3f;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.shape.Box;
+import com.jme3.scene.shape.Sphere;
+import com.jme3.system.AppSettings;
+import com.jme3.system.JmeSystem;
+
+/**
+ * 
+ * Demonstrates advanced use of the audio capture and recording
+ * features.  Multiple perspectives of the same scene are
+ * simultaneously rendered to different sound files.
+ * 
+ * A key limitation of the way multiple listeners are implemented is
+ * that only 3D positioning effects are realized for listeners other
+ * than the main LWJGL listener.  This means that audio effects such
+ * as environment settings will *not* be heard on any auxiliary
+ * listeners, though sound attenuation will work correctly.
+ * 
+ * Multiple listeners as realized here might be used to make AI
+ * entities that can each hear the world from their own perspective.
+ * 
+ * @author Robert McIntyre
+ */
+
+public class Advanced extends SimpleApplication {
+
+	/**
+	 * You will see three grey cubes, a blue sphere, and a path which
+	 * circles each cube.  The blue sphere is generating a constant
+	 * monotone sound as it moves along the track.  Each cube is
+	 * listening for sound; when a cube hears sound whose intensity is
+	 * greater than a certain threshold, it changes its color from
+	 * grey to green.
+	 * 
+	 *  Each cube is also saving whatever it hears to a file.  The
+	 *  scene from the perspective of the viewer is also saved to a
+	 *  video file.  When you listen to each of the sound files
+	 *  alongside the video, the sound will get louder when the sphere
+	 *  approaches the cube that generated that sound file.  This
+	 *  shows that each listener is hearing the world from its own
+	 *  perspective.
+	 * 
+	 */
+	public static void main(String[] args) {
+		Advanced app = new Advanced();
+		AppSettings settings = new AppSettings(true);
+		settings.setAudioRenderer(AurellemSystemDelegate.SEND);
+		JmeSystem.setSystemDelegate(new AurellemSystemDelegate());
+		app.setSettings(settings);
+		app.setShowSettings(false);
+		app.setPauseOnLostFocus(false);
+
+
+		try {
+			Capture.captureVideo(app, File.createTempFile("advanced",".avi"));
+			Capture.captureAudio(app, File.createTempFile("advanced", ".wav"));
+		}
+		catch (IOException e) {e.printStackTrace();}
+
+		app.start();
+	}
+
+
+	private Geometry bell;
+	private Geometry ear1;
+	private Geometry ear2;
+	private Geometry ear3;
+	private AudioNode music;
+	private MotionTrack motionControl;
+	private IsoTimer motionTimer = new IsoTimer(60);
+
+	private Geometry makeEar(Node root, Vector3f position){
+		Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+		Geometry ear = new Geometry("ear", new Box(1.0f, 1.0f, 1.0f));
+		ear.setLocalTranslation(position);
+		mat.setColor("Color", ColorRGBA.Green);
+		ear.setMaterial(mat);
+		root.attachChild(ear);
+		return ear;
+	} 
+
+	private Vector3f[] path = new Vector3f[]{
+			// loop 1
+			new Vector3f(0, 0, 0),
+			new Vector3f(0, 0, -10),
+			new Vector3f(-2, 0, -14),
+			new Vector3f(-6, 0, -20),
+			new Vector3f(0, 0, -26),
+			new Vector3f(6, 0, -20),
+			new Vector3f(0, 0, -14),
+			new Vector3f(-6, 0, -20),
+			new Vector3f(0, 0, -26),
+			new Vector3f(6, 0, -20),
+			// loop 2
+			new Vector3f(5, 0, -5),
+			new Vector3f(7, 0, 1.5f),
+			new Vector3f(14, 0, 2),
+			new Vector3f(20, 0, 6),
+			new Vector3f(26, 0, 0),
+			new Vector3f(20, 0, -6),
+			new Vector3f(14, 0, 0),
+			new Vector3f(20, 0, 6),
+			new Vector3f(26, 0, 0),
+			new Vector3f(20, 0, -6),
+			new Vector3f(14, 0, 0),
+			// loop 3
+			new Vector3f(8, 0, 7.5f),
+			new Vector3f(7, 0, 10.5f),
+			new Vector3f(6, 0, 20),
+			new Vector3f(0, 0, 26),
+			new Vector3f(-6, 0, 20),
+			new Vector3f(0, 0, 14),
+			new Vector3f(6, 0, 20),
+			new Vector3f(0, 0, 26),
+			new Vector3f(-6, 0, 20),
+			new Vector3f(0, 0, 14),
+			// begin ellipse
+			new Vector3f(16, 5, 20),
+			new Vector3f(0, 0, 26),
+			new Vector3f(-16, -10, 20),
+			new Vector3f(0, 0, 14),
+			new Vector3f(16, 20, 20),
+			new Vector3f(0, 0, 26),
+			new Vector3f(-10, -25, 10),
+			new Vector3f(-10, 0, 0),
+			// come at me!
+			new Vector3f(-28.00242f, 48.005623f, -34.648228f),
+			new Vector3f(0, 0 , -20),
+	};
+
+	private void createScene() {
+		Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+		bell = new Geometry( "sound-emitter" , new Sphere(15,15,1));
+		mat.setColor("Color", ColorRGBA.Blue);
+		bell.setMaterial(mat);
+		rootNode.attachChild(bell);
+
+		ear1 = makeEar(rootNode, new Vector3f(0, 0 ,-20));
+		ear2 = makeEar(rootNode, new Vector3f(0, 0 ,20));
+		ear3 = makeEar(rootNode, new Vector3f(20, 0 ,0));
+
+		MotionPath track = new MotionPath();
+
+		for (Vector3f v : path){
+			track.addWayPoint(v);
+		}
+		track.setCurveTension(0.80f);
+
+		motionControl = new MotionTrack(bell,track);
+		// for now, use reflection to change the timer... 
+		// motionControl.setTimer(new IsoTimer(60));
+		
+		try {
+			Field timerField;
+			timerField = AbstractCinematicEvent.class.getDeclaredField("timer");
+			timerField.setAccessible(true);
+			try {timerField.set(motionControl, motionTimer);} 
+			catch (IllegalArgumentException e) {e.printStackTrace();} 
+			catch (IllegalAccessException e) {e.printStackTrace();}
+		} 
+		catch (SecurityException e) {e.printStackTrace();} 
+		catch (NoSuchFieldException e) {e.printStackTrace();}
+
+
+		motionControl.setDirectionType(MotionTrack.Direction.PathAndRotation);
+		motionControl.setRotation(new Quaternion().fromAngleNormalAxis(-FastMath.HALF_PI, Vector3f.UNIT_Y));
+		motionControl.setInitialDuration(20f);
+		motionControl.setSpeed(1f);
+
+		track.enableDebugShape(assetManager, rootNode);
+		positionCamera();
+	}
+
+
+	private void positionCamera(){
+		this.cam.setLocation(new Vector3f(-28.00242f, 48.005623f, -34.648228f));
+		this.cam.setRotation(new Quaternion(0.3359635f, 0.34280345f, -0.13281013f, 0.8671653f));
+	}
+
+	private void initAudio() {
+		org.lwjgl.input.Mouse.setGrabbed(false);	
+		music = new AudioNode(assetManager, "Sound/Effects/Beep.ogg", false);
+
+		rootNode.attachChild(music);
+		audioRenderer.playSource(music);
+		music.setPositional(true);
+		music.setVolume(1f);
+		music.setReverbEnabled(false);
+		music.setDirectional(false);
+		music.setMaxDistance(200.0f);
+		music.setRefDistance(1f);
+		//music.setRolloffFactor(1f);
+		music.setLooping(false);
+		audioRenderer.pauseSource(music); 
+	}
+
+	public class Dancer implements SoundProcessor {
+		Geometry entity;
+		float scale = 2;
+		public Dancer(Geometry entity){
+			this.entity = entity;
+		}
+
+		/**
+		 * this method is irrelevant since there is no state to cleanup.
+		 */
+		public void cleanup() {}
+
+
+		/**
+		 * Respond to sound!  This is the brain of an AI entity that 
+		 * hears its surroundings and reacts to them.
+		 */
+		public void process(ByteBuffer audioSamples, int numSamples, AudioFormat format) {
+			audioSamples.clear();
+			byte[] data = new byte[numSamples];
+			float[] out = new float[numSamples];
+			audioSamples.get(data);
+			FloatSampleTools.byte2floatInterleaved(data, 0, out, 0, 
+					numSamples/format.getFrameSize(), format);
+
+			float max = Float.NEGATIVE_INFINITY;
+			for (float f : out){if (f > max) max = f;}
+			audioSamples.clear();
+
+			if (max > 0.1){entity.getMaterial().setColor("Color", ColorRGBA.Green);}
+			else {entity.getMaterial().setColor("Color", ColorRGBA.Gray);}
+		}
+	}
+
+	private void prepareEar(Geometry ear, int n){
+		if (this.audioRenderer instanceof MultiListener){
+			MultiListener rf = (MultiListener)this.audioRenderer;
+
+			Listener auxListener = new Listener();
+			auxListener.setLocation(ear.getLocalTranslation());
+
+			rf.addListener(auxListener);
+			WaveFileWriter aux = null;
+
+			try {aux = new WaveFileWriter(File.createTempFile("advanced-audio-" + n, ".wav"));} 
+			catch (IOException e) {e.printStackTrace();}
+
+			rf.registerSoundProcessor(auxListener, 
+					new CompositeSoundProcessor(new Dancer(ear), aux));
+					
+		}   
+	}
+
+
+	public void simpleInitApp() {
+		this.setTimer(new IsoTimer(60));
+		initAudio();
+
+		createScene();
+
+		prepareEar(ear1, 1);
+		prepareEar(ear2, 1);
+		prepareEar(ear3, 1);
+
+		motionControl.play();
+
+	}
+
+	public void simpleUpdate(float tpf) {
+		motionTimer.update();
+		if (music.getStatus() != AudioSource.Status.Playing){
+			music.play();
+		}
+		Vector3f loc = cam.getLocation();
+		Quaternion rot = cam.getRotation();
+		listener.setLocation(loc);
+		listener.setRotation(rot);
+		music.setLocalTranslation(bell.getLocalTranslation());
+	}
+
+}
+----
+image:http///www.youtube.com/v/oCEfK0yhDrY?.swf[oCEfK0yhDrY?.swf,with="400",height=""]
+
+
+
+=== Using Advanced features to Record from more than one perspective at once
+
+image:http///www.youtube.com/v/WIJt9aRGusc?.swf[WIJt9aRGusc?.swf,with="400",height=""]
+
+
+
+== More Information
+
+This is the old page showing the first version of this idea
+link:http://aurellem.org/cortex/html/capture-video.html[http://aurellem.org/cortex/html/capture-video.html]
+
+
+All source code can be found here:
+
+
+link:http://hg.bortreb.com/audio-send[http://hg.bortreb.com/audio-send]
+
+
+link:http://hg.bortreb.com/jmeCapture[http://hg.bortreb.com/jmeCapture]
+
+
+More information on the modifications to OpenAL to support multiple
+listeners can be found here.
+
+
+link:http://aurellem.org/audio-send/html/ear.html[http://aurellem.org/audio-send/html/ear.html]
+

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

@@ -0,0 +1,275 @@
+
+
+= JME3 Cinematics
+
+JME3 cinematics (com.jme.cinematic) allow you to remote control nodes and cameras in a 3D game: You can script and and play cinematic scenes. You can use cinematics to create link:http://en.wikipedia.org/wiki/Cutscene[cutscenes] and movies/trailers for your game. Another good use case is efficient “destruction physics: Playing back prerecorded flying pieces of debris for demolitions is much faster than calculating them with live physics.
+
+
+Internally, Cinematics are implemented as <<application_states#,AppStates>>. 
+
+
+Short overview of the cinematic process:
+
+
+.  Plan the script of your movie. +
+Write down a timeline (e.g. on paper) of which character should be at which spot at which time.
+.  Attach the scene objects that you want to remote-control to one Node. +
+This Node can be the rootNode, or a Node that is attached to the rootNode. 
+.  Create a Cinematic object for this movie scene. The Cinematic will contain and manage the movie script.
+.  For each line in your script (for each keyframe in your timeline), add a CinematicEvent to the Cinematic. 
+
+
+== Sample Code
+
+*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/animation/TestCinematic.java[TestCinematic.java]
+
+
+== How to Use a Cinematic
+
+A Cinematic is like a movie script for a node. 
+
+
+[source,java]
+----Cinematic cinematic = new Cinematic(sceneNode, duration);
+cinematic.addCinematicEvent(starttime1, event1);
+cinematic.addCinematicEvent(starttime2, event2);
+cinematic.addCinematicEvent(starttime2, event3);
+...
+stateManager.attach(cinematic);
+----
+.  Create one Cinematic per scripted scene.
+**  `sceneNode` is the node containing the scene (can be the rootNode).
+**  `duration` is the duration of the whole scene in seconds.
+**  Each Cinematic is a set of CinematicEvents, that are triggered at a given moment on the timeline.
+
+.  Create one CinematicEvent for each line of your movie script.  
+**  `event` is one motion of a moving object. You can add several events. More details below.
+**  `starttime` is the time when this particular cinematic event starts on the timeline. Specify the start time in seconds since the beginning of the cinematic.
+
+.  Attach the Cinematic to the SimpleApplication's stateManager. 
+.  Play, stop and pause the Cinematic from your code.
+[cols="2", options="header"]
+|===
+
+a|Method
+a|Usage
+
+a|cinematic.play()
+a|Starts playing the cinematic from the start, or from where it was paused.
+
+a|cinematic.stop()
+a|Stops playing the cinematic and rewinds it.
+
+a|cinematic.pause()
+a|Pauses the cinematic.
+
+|===
+
+
+== Events(CinematicEvents)
+
+Just like a movie script consists of lines with instructions to the actors, each Cinematic consists of a series of events.
+
+
+Here is the list of available CinematicEvents that you use as events. Each track remote-controls scene objects in a different way:
+
+[cols="2", options="header"]
+|===
+
+a|Events(CinematicEvents)
+a|Description
+
+a|MotionEvent
+a|Use a MotionEvent to move a Spatial non-linearly over time. A MotionEvent is based on a list of waypoints in a MotionPath. The curve goes through each waypoint, and you can adjust the tension of the curve to modify the roundedness of the path. This is the motion interpolation you are going to use in most cases. 
+
+a|SoundEvent
+a|Use a SoundEvent to play a <<audio#,sound>> at a given time for the given duration.
+
+a|GuiEvent
+a|Displays a <<nifty_gui#,Nifty GUI>> at a given time for the given duration. Use it to display subtitles or HUD elements. Bind the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ XML to the cinematic using `cinematic.bindUi(“path/to/nifty/file.xml);`
+
+a|AnimationEvent
+a|Use this to start playing a model <<animation#,animation>> at a given time (a character walking animation for example)
+
+|===
+
+You can add custom events by extending AbstractCinematicEvent.
+
+
+
+=== MotionEvent
+
+A MotionEvent moves a Spatial along a complex path.
+
+
+[source,java]
+----MotionEvent events= new MotionEvent (thingNode, path);----
+Details of the constructor:
+
+
+*  `thingNode` is the Spatial to be moved.
+*  `path` is a complex <<motionpath#,MotionPath>>.
+
+To create a MotionEvent, do the following:
+
+
+.  <<motiontrack#,Create a MotionEvent>>
+.  Create a MotionEvent based on the MotionPath.
+.  Configure your MotionEvent (see below).
+.  Add the MotionEvent to a Cinematic.
+[cols="2", options="header"]
+|===
+
+a|MotionEvent configuration method
+a|Usage
+
+a|event.setLoopMode(LoopMode.Loop)
+a|Sets whether the animation along this path should loop (LoopMode.Loop) or play only once (LoopMode.DontLoop).
+
+a|event.setDirectionType(MotionEvent.Direction.None)
+a|Sets the direction behavior type of the controlled node. Direction.None deactivates this feature. You can choose from the following options: LookAt, Path, PathAndRotation, Rotation.
+
+a|event.setDirectionType(MotionEvent.Direction.LookAt)
+a|The spatial turns (rotates) to keep facing a certain point while moving. Specify the point with the `setLookAt()` method.
+
+a|event.setDirectionType(MotionEvent.Direction.Path)
+a|The spatial always faces in the direction of the path while moving.
+
+a|event.setDirectionType(MotionEvent.Direction.PathAndRotation)
+a|The spatial faces the direction of the path, plus an added rotation. Use together with the `setRotation()` method.
+
+a|event.setDirectionType(MotionEvent.Direction.Rotation)
+a|The spatial spins (rotates) while moving. You describe the spin by a custom quaternion. Use together with the `setRotation()` method.
+
+a|event.setLookAt(teapot.getWorldTranslation(), Vector3f.UNIT_Y)
+a|The spatial always faces towards this location. Use together with `MotionEvent.Direction.LookAt`.
+
+a|event.setRotation(quaternion)
+a|Sets the rotation. Use together with `MotionEvent.Direction.Rotation` or `MotionEvent.Direction.PathAndRotation`.
+
+|===
+
+*Tip:* Most likely you remote-control more than one object in your scene. Give the events and paths useful names such as `dragonEvent`, `dragonPath`, `heroEvent`, `heroPath`, etc.
+
+
+
+=== SoundEvent
+
+A SoundEventplays a sound as part of the cinematic. 
+
+
+[source,java]
+----SoundEvent( audioPath, isStream, duration, loopMode )----
+Details of the constructor:
+
+
+*  `audioPath` is the path to an audio file as String, e.g. “Sounds/mySound.wav.
+*  `isStream` toggles between streaming and buffering. Set to true to stream long audio file, set to false to play short buffered sounds.
+*  `duration` is the time that it should take to play.
+*  `loopMode` can be LoopMode.Loop, LoopMode.DontLoop, LoopMode.Cycle.
+
+
+=== GuiEvent
+
+A GuiEventshows or hide a NiftyGUI as part of a cinematic.
+
+
+[source,java]
+----GuiEvent( screen, duration, loopMode )----
+You must use this together with bindUI() to specify the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ XML file that you want to load:
+
+
+[source,java]
+----cinematic.bindUi("Interface/subtitle.xml");----
+Details of the constructor:
+
+
+*  `screen` is the name of the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ screen to load, as String. 
+*  `duration` is the time that it should take to play.
+*  `loopMode` can be LoopMode.Loop, LoopMode.DontLoop, LoopMode.Cycle.
+
+
+=== AnimationEvent
+
+An AnimationEvent triggers an animation as part of a cinematic.
+
+
+[source,java]
+----AnimationEvent( thingNode, animationName, duration, loopMode )----
+Details of the constructor:
+
+
+*  `thingNode` is the Spatial whose animation you want to play.
+*  `animationName` the name of the animation stored in the animated model that you want to trigger, as a String.
+*  `duration` is the time that it should take to play.
+*  `loopMode` can be LoopMode.Loop, LoopMode.DontLoop, LoopMode.Cycle.
+
+
+=== Camera Management
+
+There is a built in system for camera switching in Cinematics. It based on CameraNode, and the cinematic just enable the given CameraNode control at a given time.
+
+
+First you have to bind a camera to the cinematic with a unique name. You'll be provided with a CameraNode
+
+
+[source,java]
+----
+ CameraNode camNode = cinematic.bindCamera("topView", cam);
+----
+then you can do whatever you want with this camera node : place it so that you have a the camera angle you'd like, attach it to a motion event to have some camera scrolling, attach control of your own that give it whatever behavior you'd like.
+In the above example, I want it to be a top view of the scene looking at the world origin.
+
+
+[source,java]
+----
+ //set its position
+ camNode.setLocalTranslation(new Vector3f(0, 50, 0));
+ // set it to look at the world origin
+ camNode.lookAt(Vector3F.ZERO, Vector3f.UNIT_Y);
+----
+Then i just have to schedule its activation in the cinematic. I want it to get activated 3 seconds after the start of the cinematic so I just have to do 
+
+
+[source,java]
+----
+ cinematic.activateCamera(3,”topView”);
+----
+
+=== Customizations
+
+You can extend individual CinematicEvents. The link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/animation/SubtitleTrack.java[SubtitleTrack.java example] shows how to extend a GuiTrack to script subtitles. See how the subtitles are used in the link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/animation/TestCinematic.java[TestCinematic.java example].
+
+
+You can also create new CinematicEvent by extending link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/cinematic/events/AbstractCinematicEvent.java[AbstractCinematicEvent]. An AbstractCinematicEvent implements the CinematicEvent interface and provides duration, time, speed, etc… management. Look at the link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/animation/TestCinematic.java[TestCinematic.java example] is to use this for a custom fadeIn/fadeOut effect in combination with a com.jme3.post.filters.FadeFilter.
+
+
+
+== Interacting with Cinematics
+
+
+=== CinematicEventListener
+
+[source,java]
+----CinematicEventListener cel = new CinematicEventListener() {
+  public void onPlay(CinematicEvent cinematic) {
+    chaseCam.setEnabled(false);
+    System.out.println("play");
+  }
+
+  public void onPause(CinematicEvent cinematic) {
+    chaseCam.setEnabled(true);
+    System.out.println("pause");
+  }
+
+  public void onStop(CinematicEvent cinematic) {
+    chaseCam.setEnabled(true);
+    System.out.println("stop");
+  }
+}
+cinematic.addListener(cel);----
+
+=== Physics Interaction
+
+Upcoming.
+

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

@@ -0,0 +1,188 @@
+
+
+= Collision and Intersection
+
+The term collision can be used to refer to <<jme3/advanced/physics_listeners#,physical interactions>> (where <<jme3/advanced/physics#,physical objects>> collide, push and bump off one another), and also to non-physical _intersections_ in 3D space. This article is about the non-physical (mathematical) collisions.
+
+
+Non-physical collision detection is interesting because it uses less computing resources than physical collision detection. The non-physical calculations are faster because they do not have any side effects such as pushing other objects or bumping off of them. Tasks such as <<mouse_picking#,mouse picking>> are easily implemented using mathematical techniques such as ray casting and intersections.  Experienced developers optimize their games by finding ways to simulate certain (otherwise expensive physical) interactions in a non-physical way. 
+
+
+*Example:* One example for an optimization is a physical vehicle's wheels. You could make the wheels fully physical disks, and have jME calculate every tiny force – sounds very accurate? It's total overkill and too slow for a racing game. A more performant solution is to cast four invisible rays down from the vehicle and calculate the intersections with the floor. These non-physical wheels require (in the simplest case) only four calculations per tick to achieve an effect that players can hardly distinguish from the real thing.
+
+
+
+== Collidable
+
+The interface com.jme3.collision.Collidable declares one method that returns how many collisions were found between two Collidables: `collideWith(Collidable other, CollisionResults results)`.
+
+
+*  A `com.jme3.collision.CollisionResults` object is an ArrayList of comparable `com.jme3.collision.CollisionResult` objects.
+*  You can iterate over the CollisionResults to identify the other parties involved in the collision. +
+Note that jME counts _all_ collisions, this means a ray intersecting a box will be counted as two hits, one on the front where the ray enters, and one on the back where the ray exits.
+[cols="2", options="header"]
+|===
+
+a|CollisionResults Method
+a|Usage
+
+<a|size()                
+a|Returns the number of CollisionResult objects.
+
+a|getClosestCollision() 
+a|Returns the CollisionResult with the lowest distance.
+
+a|getFarthestCollision()
+a|Returns the CollisionResult with the farthest distance.
+
+<a|getCollision(i)       
+a|Returns the CollisionResult at index i.
+
+|===
+
+A CollisionResult object contains information about the second party of the collision event.
+
+[cols="2", options="header"]
+|===
+
+a|CollisionResult Method
+a|Usage
+
+a|getContactPoint()
+a|Returns the contact point coordinate on the second party, as Vector3f.
+
+a|getContactNormal()
+a|Returns the Normal vector at the contact point, as Vector3f.
+
+a|getDistance()
+a|Returns the distance between the Collidable and the second party, as float.
+
+a|getGeometry()
+a|Returns the Geometry of the second party.
+
+a|getTriangle(t)
+a|Binds t to the triangle t on the second party's mesh that was hit.
+
+a|getTriangleIndex()
+a|Returns the index of the triangle on the second party's mesh that was hit.
+
+|===
+
+
+=== Code Sample
+
+Assume you have two collidables a and b and want to detect collisions between them. The collision parties can be Geometries, Nodes with Geometries attached (including the rootNode), Planes, Quads, Lines, or Rays. An important restriction is that you can only collide geometry vs bounding volumes or rays. (This means for example that a must be of Type Node or Geometry and b respectively of Type BoundingBox, BoundingSphere or Ray.)
+
+
+The following code snippet can be triggered by listeners (e.g. after an input action such as a click), or timed in the update loop.
+
+
+[source,java]
+----
+  // Calculate detection results
+  CollisionResults results = new CollisionResults();
+  a.collideWith(b, results);
+  System.out.println("Number of Collisions between" + 
+      a.getName()+ " and " + b.getName() + ": " + results.size());
+  // Use the results
+  if (results.size() > 0) {
+    // how to react when a collision was detected
+    CollisionResult closest  = results.getClosestCollision();
+    System.out.println("What was hit? " + closest.getGeometry().getName() );
+    System.out.println("Where was it hit? " + closest.getContactPoint() );
+    System.out.println("Distance? " + closest.getDistance() );
+  } else {
+    // how to react when no collision occured
+  }
+}----
+You can also loop over all results and trigger different reactions depending on what was hit and where it was hit. In this example, we simply print info about them.
+
+
+[source,java]
+----
+  // Calculate Results
+  CollisionResults results = new CollisionResults();
+  a.collideWith(b, results);
+  System.out.println("Number of Collisions between" + a.getName()+ " and "
+   + b.getName() " : " + results.size());
+  // Use the results
+  for (int i = 0; i < results.size(); i++) {
+    // For each hit, we know distance, impact point, name of geometry.
+    float     dist = results.getCollision(i).getDistance();
+    Vector3f    pt = results.getCollision(i).getContactPoint();
+    String   party = results.getCollision(i).getGeometry().getName();
+    int        tri = results.getCollision(i).getTriangleIndex();
+    Vector3f  norm = results.getCollision(i).getTriangle(new Triangle()).getNormal();
+    System.out.println("Details of Collision #" + i + ":");
+    System.out.println("  Party " + party + " was hit at " + pt + ", " + dist + " wu away.");
+    System.out.println("  The hit triangle #" + tri + " has a normal vector of " + norm);
+  }
+----
+Knowing the distance of the collisions is useful for example when you intersect Lines and Rays with other objects.
+
+
+
+== Bounding Volumes
+
+A `com.jme3.bounding.BoundingVolume` is an interface for dealing with containment of a collection of points. All BoundingVolumes are `Collidable` and are used as optimization to calculate non-physical collisions more quickly: It's always faster to calculate an intersection between simple shapes like spheres and boxes than between complex shapes like models. 
+
+
+jME3 computes bounding volumes for all objects. These bounding volumes are later used for frustum culling, which is making sure only objects visible on-screen are actually sent for rendering. 
+
+
+All fast-paced action and shooter games use BoundingVolumes as an optimization. Wrap all complex models into simpler shapes – in the end, you get equally useful collision detection results, but faster. link:http://en.wikipedia.org/wiki/Bounding_volume[More about bounding volumes...]
+
+
+Supported types:
+
+image::http///www.jmonkeyengine.com/jme/wiki-data/userref/capsule.png[Capsule,with="150",height="110",align="right"]
+
+
+
+*  Type.AABB = Axis-aligned bounding box, that means it doesn't rotate, which makes it less precise. A `com.jme3.bounding.BoundingBox` is an axis-aligned cuboid used as a container for a group of vertices of a piece of geometry. A BoundingBox has a center and extents from that center along the x, y and z axis. This is the default bounding volume, since it is fairly fast to generate and gives better accuracy than the bounding sphere.
+*  Type.Sphere: `com.jme3.bounding.BoundingSphere` is a sphere used as a container for a group of vertices of a piece of geometry. A BoundingSphere has a center and a radius.
+*  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>>
+
+
+
+=== Usage
+
+For example you can use Bounding Volumes on custom meshes, or complex non-physical shapes.
+
+
+[source,java]
+----mesh.setBound(new BoundingSphere());
+mesh.updateBound();----
+
+== Mesh and Scene Graph Collision
+
+One of the supported `Collidable`s are meshes and scene graph objects. To execute a collision detection query against a scene graph, use `Spatial.collideWith()`. This will traverse the scene graph and return any mesh collisions that were detected. Note that the first collision against a particular scene graph may take a long time, this is because a special data structure called link:http://en.wikipedia.org/wiki/Bounding_interval_hierarchy[|Bounding Interval Hierarchy (BIH)] needs to be generated for the meshes. At a later point, the mesh could change and the BIH tree would become out of date, in that case, call link:http://jmonkeyengine.org/javadoc/com/jme3/scene/Mesh.html#createCollisionData()[Mesh.createCollisionData()] on the changed mesh to update the BIH tree.
+
+
+
+== Intersection
+
+A `com.jme3.math.Ray` is an infinite line with a beginning, a direction, and no end; whereas a `com.jme3.math.Line` is an infinite line with only a direction (no beginning, no end).
+
+
+Rays are used to perform line-of-sight calculations. This means you can detect what users were “aiming at when they clicked or pressed a key. You can also use this to detect whether game characters can see something (or someone) or not.
+
+
+*  *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.
+
+–
+
+
+Learn the details of how to implement <<jme3/advanced/mouse_picking#,Mouse Picking>> here.
+
+'''
+
+TODO:
+
+
+*  Bounding Interval Hierarchy (`com.jme3.collision.bih.BIHNode`)
+*  com.jme3.scene.CollisionData

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

@@ -0,0 +1,225 @@
+
+
+= Combo Moves
+
+The ComboMoves class allows you to define combinations of inputs that trigger special actions. Entering an input combo correctly can bring the player incremental rewards, such as an increased chance to hit, an increased effectiveness, or decreased change of being blocked, whatever the game designer chooses. link:http://en.wikipedia.org/wiki/Combo_%28video_gaming%29[More background info]
+
+
+Combos are usually a series of inputs, in a fixed order: For example a keyboard combo can look  like: “press Down, then Down+Right together, then Right. 
+
+
+Usage:
+
+
+.  Create input triggers 
+.  Define combos
+.  Detect combos in ActionListener 
+.  Execute combos in update loop 
+
+Copy the two classes ComboMoveExecution.java and ComboMove.java into your application and adjust them to your package paths.
+
+
+
+== Example Code
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/combomoves/TestComboMoves.java[TestComboMoves.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/combomoves/ComboMoveExecution.java[ComboMoveExecution.java] ← required
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/combomoves/ComboMove.java[ComboMove.java] ← required
+
+
+== Create Input Triggers
+
+First you <<jme3/advanced/input_handling#,define your game's inputs>> as you usually do: Implement the com.jme3.input.controls.ActionListener interface for your class, and add triggers mappings such as com.jme3.input.controls.KeyTrigger and com.jme3.input.KeyInput. 
+
+
+For example:
+
+
+[source,java]
+----
+inputManager.addMapping("Left",    new KeyTrigger(KeyInput.KEY_LEFT));
+inputManager.addMapping("Right",   new KeyTrigger(KeyInput.KEY_RIGHT));
+inputManager.addMapping("Up",      new KeyTrigger(KeyInput.KEY_UP));
+inputManager.addMapping("Down",    new KeyTrigger(KeyInput.KEY_DOWN));
+inputManager.addMapping("Attack1", new KeyTrigger(KeyInput.KEY_SPACE));
+...
+inputManager.addListener(this, "Left", "Right", "Up", "Down", "Attack1");
+----
+
+== Define Combos
+
+For each of  your combo moves, you specify the series of inputs that will trigger it. The order in which you define them is the order the player has to press them for the step to be recorded. When all steps have been recorded, the combo is triggered. 
+
+
+The following example shows how a fireball combo move is triggered by pressing the navigation keys for “down, down+right, right, in this order.
+
+
+[source,java]
+----
+ComboMove fireball = new ComboMove("Fireball");
+fireball.press("Down").notPress("Right").done();
+fireball.press("Right", "Down").done();
+fireball.press("Right").notPress("Down").done();
+fireball.notPress("Right", "Down").done();
+fireball.setUseFinalState(false);
+----
+Also create a ComboMoveExecution object for each ComboMove. You need it later to execute the detected combo.
+
+
+[source,java]
+----
+ComboMoveExecution fireballExec = new ComboMoveExecution(fireball);
+----
+
+=== ComboMove Class Methods
+
+Use the following ComboMove methods to specify the combo:
+
+[cols="2", options="header"]
+|===
+
+a|ComboMove Method
+a|Description
+
+a|press(“A).done(); +
+press(“A,“B).done();
+a|Combo step is recorded if A is entered. +
+Combo step is recorded if A and B are entered simultaneously.
+
+a|notPress(“A).done(); +
+notPress(“A,“B).done();
+a|Combo step is recorded if A is released. +
+Combo step is recorded if A and B are both released.
+
+a|press(“A).notPress(“B).done();
+a|Combo step is recorded if A is entered, and not B
+
+a|press(“A).notPress(“B).timeElapsed(0.11f).done();
+a|Combo step is recorded a certain time after A and not B is entered. +
+etc, etc …
+
+a|setPriority(0.5f);
+a|If there is an ambiguity, a high-priority combo will trigger instead of a low-priority combo. This prevents that a similar looking combo step “hijacks another Combo. Use only once per ComboMove.
+
+a|setUseFinalState(false); +
+setUseFinalState(true);
+a|This is the final command of the series. +
+False: Do not wait on a final state, chain combo steps. (?) +
+True: This is the final state, do not chain combo steps. (?)
+
+|===
+
+The `press()` and `notPress()` methods accept sets of Input Triggers, e.g. `fireball.press(“A,“B,“C).done()`.
+
+
+The following getters give you more information about the game state:
+
+[cols="2", options="header"]
+|===
+
+a|ComboMove Method
+a|Usage
+
+a|getCastTime()
+a|Returns the time since the last step has been recorded. (?)
+
+a|getMoveName()
+a|Returns the string of the current combo
+
+a|getPriority()
+a|Returns the priority of this move
+
+|===
+
+
+== Detect Combos in ActionListener
+
+Now that you have specified the combo steps, you want to detect them. You do that in the onAction() method that you get from the ActionListener interface.
+
+
+Create a HashSet `pressMappings` to track curently pressed mappings, and a ComboMove object `currentMove` to track the current move. 
+
+
+We also track the cast time of a combo to determine if it has timed out (see update loop below).
+
+
+[source,java]
+----
+private HashSet<String> pressedMappings = new HashSet<String>();
+private ComboMove currentMove = null;
+private float currentMoveCastTime = 0;
+private float time = 0;
+...
+
+public void onAction(String name, boolean isPressed, float tpf) {
+    // Record pressed mappings
+    if (isPressed){
+        pressedMappings.add(name);
+    }else{
+        pressedMappings.remove(name);
+    }
+
+    // The pressed mappings have changed: Update ComboExecution objects
+    List<ComboMove> invokedMoves = new ArrayList<ComboMove>();
+    if (fireballExec.updateState(pressedMappings, time)){
+        invokedMoves.add(fireball);
+    }
+    // ... add more ComboExecs here...
+
+    // If any ComboMoves have been sucessfully triggered:
+    if (invokedMoves.size() > 0){
+        // identify the move with highest priority
+        float priority = 0;
+        ComboMove toExec = null;
+        for (ComboMove move : invokedMoves){
+            if (move.getPriority() > priority){
+                priority = move.getPriority();
+                toExec = move;
+            }
+        }
+        if (currentMove != null && currentMove.getPriority() > toExec.getPriority()){
+            return; // skip lower-priority moves
+        }
+
+        // If a ComboMove has been identified, store it in currentMove
+        currentMove = toExec;
+        currentMoveCastTime = currentMove.getCastTime();
+    }
+}
+----
+
+== Execute Combos in the Update Loop
+
+Now that you have detected the current move, you want to execute it. You do that in the update loop.
+
+
+[source,java]
+----
+@Override
+public void simpleUpdate(float tpf){
+    time += tpf;
+    fireballExec.updateExpiration(time); 
+    // ... update more ComboExecs here....
+
+    if (currentMove != null){
+        currentMoveCastTime -= tpf;
+        if (currentMoveCastTime <= 0){
+            System.out.println("THIS COMBO WAS TRIGGERED: " + currentMove.getMoveName());
+            // TODO: for each combo, implement special actions here
+            currentMoveCastTime = 0;
+            currentMove = null;
+        }
+    }
+}----
+Test `currentMove.getMoveName()` and proceed to call methods that implement any special actions and bonuses. This is up to you and depends individually on your game.
+
+
+
+== Why Combos?
+
+Depending on the game genre, the designer can reward the players' intrinsical or extrinsical skills:
+
+
+*  (intrinsical:) RPGs typically calculate the success of an attack from the character's in-game training level: The player plays the role of a character whose skill level is defined in numbers. RPGs typically do not offer any Combos.
+*  (extrinsical:) Sport and fighter games typically choose to reward the player's “manual skills: The success of a special move solely depends on the player's own dexterity. These games typically offer optional Combos.
+<tags><tag target="keyinput" /><tag target="input" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,308 @@
+
+
+= Custom Controls
+
+A `com.jme3.scene.control.Control` is a customizable jME3 interface that allows you to cleanly steer the behaviour of game entities (Spatials), such as artificially intelligent behaviour in NPCs, traps, automatic alarms and doors, animals and pets, self-steering vehicles or platforms – anything that moves and interacts. Several instances of custom Controls together implement the behaviours of a type of Spatial. 
+
+
+To control global game behaviour see <<jme3/advanced/application_states#,Application States>> – you often use AppStates and Control together.
+
+
+*  link:http://www.youtube.com/watch?v=MNDiZ9YHIpM[Quick video introduction to Custom Controls]
+
+To control the behaviour of spatials:
+
+
+.  Create one control for each _type of behavior_. When you add several controls to one spatial, they will be executed in the order they were added. +
+For example, one NPC can be controlled by a PhysicsControl instance and an AIControl instance.
+.  Define the custom control and implement its behaviour in the Control's update method:
+**  You can pass arguments into your custom control.
+**  In the control class, the object `spatial` gives you access to the spatial and subspatials that the control is attached to.
+**  Here you modify the `spatial`'s transformation (move, scale, rotate), play animations, check its environement, define how it acts and reacts. 
+
+.  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);----
+
+To implement game logic for a type of spatial, you will either extend AbstractControl (most common case), or implement the Control interface, as explained in this article.
+
+
+
+== Usage
+
+Use <<jme3/advanced/custom_controls#,Controls>> to implement the _behaviour of types of game entities_.
+
+
+*  Use Controls to add a type of behaviour (that is, methods and fields) to individual Spatials. 
+*  Each Control has its own `update()` loop that hooks into `simpleUpdate()`. Use Controls to move blocks of code out of the `simpleUpdate()` loop.
+*  One Spatial can be influenced by several Controls. (Very powerful and modular!) 
+*  Each Spatial needs its own instance of the Control. 
+*  A Control only has access to and control over the Spatial it is attached to.
+*  Controls can be saved as .j3o file together with a Spatial. 
+
+Examples: You can write
+
+
+*  A WalkerNavControl, SwimmerNavControl, FlyerNavControl… that defines how a type of NPC finds their way around. All NPCs can walk, some can fly, others can swim, and some can all three, etc.
+*  A PlayerNavControl that is steered by user-configurable keyboard and mouse input.
+*  A generic animation control that acts as a common interface that triggers animations (walk, stand, attack, defend) for various entities.
+*  A DefensiveBehaviourControl that remote-controls NPC behaviour in fight situations. 
+*  An IdleBehaviourControl that remote-controls NPC behaviour in neutral situations. 
+*  A DestructionControl that automatically replaces a structure with an appropriate piece of debris after collision with a projectile… 
+
+The possibilities are endless. emoji:smiley
+
+
+
+== Example Code
+
+Other examples include the built-in RigidBodyControl in JME's physics integration, the built-in TerrainLODControl that updates the terrain's level of detail depending on the viewer's perspective, etc.
+
+
+Existing examples in the code base include:
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/animation/AnimControl.java[AnimControl.java] allows manipulation of skeletal animation, including blending and multiple channels.
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/scene/control/CameraControl.java[CameraControl.java] allows you to sync the camera position with the position of a given spatial.
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/scene/control/BillboardControl.java[BillboardControl.java] displays a flat picture orthogonally, e.g. a speech bubble or informational dialog.
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/#src%2Fjbullet%2Fcom%2Fjme3%2Fbullet%2Fcontrol[PhysicsControl] subclasses (such as CharacterControl, RigidBodyControl, VehicleControl) allow you to add physical properties to any spatial. PhysicsControls tie into capabilities provided by the BulletAppState.
+
+
+== AbstractControl Class
+
+
+
+
+The AbstractControl can be found under `com.jme3.scene.control.AbstractControl`. This is a default abstract class that implements the Control interface.
+
+
+*  You have access to a boolean `isEnabled()`.
+*  You have access to the Spatial object `spatial`. 
+*  You override the `controlUpdate()` method to implement the Spatial's behaviour. 
+*  You have access to a `setEnabled(boolean)` method. This activates or deactivates this Control's behaviour in this spatial temporarily. While the AbstractControl is toggled to be disabled, the `controlUpdate()` loop is no longer executed. +
+For example, you disable your IdleBehaviourControl when you enable your DefensiveBehaviourControl in a spatial.
+
+Usage: Your custom subclass implements the three methods `controlUpdate()`, `controlRender()`, `setSpatial()`, and `cloneForSpatial()` as shown here:
+
+
+[source,java]
+----
+public class MyControl extends AbstractControl implements Savable, Cloneable {
+  private int index; // can have custom fields -- example 
+  
+  public MyControl(){} // empty serialization constructor
+  
+  /** Optional custom constructor with arguments that can init custom fields.
+    * Note: you cannot modify the spatial here yet! */
+  public MyControl(int i){ 
+    // index=i; // example 
+  } 
+  
+  /** This method is called when the control is added to the spatial,
+    * and when the control is removed from the spatial (setting a null value).
+    * It can be used for both initialization and cleanup. */    
+  @Override
+  public void setSpatial(Spatial spatial) {
+    super.setSpatial(spatial);
+    /* Example:
+    if (spatial != null){
+        // initialize
+    }else{
+        // cleanup
+    }
+    */
+  }
+
+
+  /** Implement your spatial's behaviour here.
+    * From here you can modify the scene graph and the spatial
+    * (transform them, get and set userdata, etc).
+    * This loop controls the spatial while the Control is enabled. */
+  @Override
+  protected void controlUpdate(float tpf){
+    if(spatial != null) {
+      // spatial.rotate(tpf,tpf,tpf); // example behaviour
+    }
+  }
+  
+  @Override
+  public Control cloneForSpatial(Spatial spatial){
+    final MyControl control = new MyControl();
+    /* Optional: use setters to copy userdata into the cloned control */
+    // control.setIndex(i); // example
+    control.setSpatial(spatial);
+    return control;
+  }
+  
+  @Override
+  protected void controlRender(RenderManager rm, ViewPort vp){
+     /* Optional: rendering manipulation (for advanced users) */
+  }
+  
+  @Override
+  public void read(JmeImporter im) throws IOException {
+      super.read(im);
+      // im.getCapsule(this).read(...);
+  }
+  
+  @Override
+  public void write(JmeExporter ex) throws IOException {
+      super.write(ex);
+      // ex.getCapsule(this).write(...);
+  }
+  
+}----
+See also:
+
+
+*  To learn more about `write()` and `read()`, see <<save_and_load#,Save and Load>>
+*  To learn more about `setUserData()`, see <<spatial#,Spatial>>.
+
+
+== The Control Interface
+
+
+
+
+The Control interface can be found under `com.jme3.scene.control.Control`. It has the following method signatures:
+
+
+*  `cloneForSpatial(Spatial)`: Clones the Control and attaches it to a clone of the given Spatial. +
+Implement this method to be able to <<save_and_load#,save() and load()>> Spatials carrying this Control. +
+The AssetManager also uses this method if the same spatial is loaded twice. You can specify which fields you want your object to reuse (e.g. collisionshapes) in this case. 
+*  `setEnabled(boolean)`: Toggles a boolean that enables or disables the Control. Goes with accessor `isEnabled();`. You test for it in the `update(float tpf)` loop before you execute anything.
+*  There are also some internal methods that you do not call from user code: `setSpatial(Spatial s)`, `update(float tpf);`, `render(RenderManager rm, ViewPort vp)`.
+
+Usage example:
+1. Create a custom control interface
+
+
+[source,java]
+----public interface MyControlInterface extends Control {
+    public void setSomething(int x); // optionally, add custom methods
+}----
+2. Create custom Controls implementing your Control interface.
+
+
+[source,java]
+----public class MyControl extends MyCustomClass implements MyControlInterface {
+
+    protected Spatial spatial;
+
+    protected boolean enabled = true;
+
+    public MyControl() { } // empty serialization constructor
+
+    public MyControl(int x) { // custom constructor
+        super(x);
+    }
+
+    @Override
+    public void update(float tpf) {
+        if (enabled && spatial != null) {
+            // Write custom code to control the spatial here!
+        }
+    }
+    
+    @Override
+    public void render(RenderManager rm, ViewPort vp) {
+        // optional for advanced users, e.g. to display a debug shape
+    }
+    
+    @Override
+    public Control cloneForSpatial(Spatial spatial) {
+        MyControl control = new MyControl();
+        // set custom properties
+        control.setSpatial(spatial);
+        control.setEnabled(isEnabled()); 
+        // set some more properties here...
+        return control;
+    }
+    
+    @Override
+    public void setEnabled(boolean enabled) {
+        this.enabled = enabled;
+    }
+    
+    @Override
+    public boolean isEnabled() {
+        return enabled;
+    }
+    
+    @Override
+    public void setSomething(int z) {
+        // You can add custom methods ...
+    }
+    
+    @Override
+    public void write(JmeExporter ex) throws IOException {
+        super.write(ex);
+        OutputCapsule oc = ex.getCapsule(this);
+        oc.write(enabled, "enabled", true);
+        oc.write(spatial, "spatial", null);
+        // write custom variables ....
+    }
+    @Override
+    public void read(JmeImporter im) throws IOException {
+        super.read(im);
+        InputCapsule ic = im.getCapsule(this);
+        enabled = ic.readBoolean("enabled", true);
+        spatial = (Spatial) ic.readSavable("spatial", null);
+        // read custom variables ....
+    }
+}----
+
+== Best Practices
+
+*Tip:* Use the getControl() accessor to get Control objects from Spatials. No need to pass around lots of object references.
+Here an example from the link:http://code.google.com/p/monkeyzone/[MonkeyZone] code:
+
+
+[source,java]
+----
+public class CharacterAnimControl implements Control {
+  ...
+  public void setSpatial(Spatial spatial) {
+    ...
+    animControl      = spatial.getControl(AnimControl.class);
+    characterControl = spatial.getControl(CharacterControl.class);
+    ...
+  }
+}----
+*Tip:* You can create custom Control interfaces so a set of different Controls provide the same methods and can be accessed with the interface class type.
+
+
+[source,java]
+----public interface ManualControl extends Control {
+    public void steerX(float value);
+    public void steerY(float value);
+    public void moveX(float value);
+    public void moveY(float value);
+    public void moveZ(float value);
+   ...
+}----
+Then you create custom sub-Controls and implement the methods accordingly to the context:
+
+
+[source,java]
+----public class ManualVehicleControl   extends ManualControl {...}----
+ and
+
+
+[source,java]
+----public class ManualCharacterControl extends ManualControl {...}----
+Then add the appropriate controls to spatials:
+
+
+[source,java]
+----
+characterSpatial.addControl(new ManualCharacterControl());
+...
+vehicleSpatial.addControl(new ManualVehicleControl());
+...----
+*Tip:* Use the getControl() method on a Spatial to get a specific Control object, and activate its behaviour!
+
+
+[source,java]
+----ManualControl c = mySpatial.getControl(ManualControl.class);
+c.steerX(steerX);----

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

@@ -0,0 +1,327 @@
+
+
+= Custom Mesh Shapes
+
+
+image::http///wiki.jmonkeyengine.org/lib/exe/fetch.php/jme3/advanced/custom_mesh.png[custom_mesh.png,with="150",height="150",align="left"]
+
+Use the Mesh class to create custom shapes that go beyond Quad, Box, Cylinder, and Sphere, even procedural shapes are possible. Thank you to KayTrance for providing the sample code!
+
+
+*Note:* In this tutorial, we (re)create a very simple rectangular mesh (a quad), and we have a look at different ways of coloring it. Coding a custom quad may not be very useful because it's exactly the same as the built-in `com.jme3.scene.shape.Quad`. We chose a simple quad to teach you how to build any shape out of triangles, without the distractions of more complex shapes.
+
+
+*  Full code sample: link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/model/shape/TestCustomMesh.java[TestCustomMesh.java]
+
+
+== Polygon Meshes
+
+Polygon <<mesh#,mesh>>es are made up of triangles. The corners of the triangles are called vertices. When ever you create any new shape, you break it down into triangles.
+
+
+*Example:* Let's look at a cube. A cube is made up of 6 rectangles. Each rectangle can be broken down into two triangles. This means you need 12 triangles to describe a cube mesh. Therefor you must provide the coordinates of the triangles' 8 corners (called vertices). 
+
+
+The important thing is that you have to specify the vertices of each triangle in the right order: Each triangle separately, counter-clockwise. 
+
+
+Sounds harder than it is – let's create a simple custom mesh, a quad.
+
+
+
+== Creating a Quad Mesh
+
+In this tutorial we want to create a 3x3 Quad. The quad has four vertices, and is made up of two triangles. In our example, we decide that the bottom left corner is at 0/0/0 and the top right is at 3/3/0. 
+
+
+[source]
+----0,3,0--3,3,0
+| \        |
+|   \      |
+|     \    |
+|       \  |
+|         \|
+0,0,0--3,0,0----
+
+=== The Mesh Object
+
+The base class for creating meshes is `com.jme3.scene.Mesh`.
+
+
+[source,java]
+----Mesh mesh = new Mesh();----
+Tip: If you create your own Mesh-based class (`public class MyMesh extends Mesh {  }`), replace the variable `mesh` by `this` in the following examples.
+
+
+
+=== Vertex Coordinates
+
+To define your own shape, determine the shape's *vertex coordinates* in 3D space. Store the list of corner positions in an `com.jme3.math.Vector3f` array. For a Quad, we need four vertices: Bottom left, bottom right, top left, top right. We name the array `vertices[]`.
+
+
+[source,java]
+----
+Vector3f [] vertices = new Vector3f[4];
+vertices[0] = new Vector3f(0,0,0);
+vertices[1] = new Vector3f(3,0,0);
+vertices[2] = new Vector3f(0,3,0);
+vertices[3] = new Vector3f(3,3,0);
+----
+
+=== Texture Coordinates
+
+Next, we define the Quad's 2D *texture coordinates* for each vertex, in the same order as the vertices: Bottom left, bottom right, top left, top right. We name this Vector2f array `texCoord[]`
+
+
+[source,java]
+----
+Vector2f[] texCoord = new Vector2f[4];
+texCoord[0] = new Vector2f(0,0);
+texCoord[1] = new Vector2f(1,0);
+texCoord[2] = new Vector2f(0,1);
+texCoord[3] = new Vector2f(1,1);
+----
+This syntax means, when you apply a texture to this mesh, the texture will fill the quad from corner to corner at 100% percent size. Especially when you stitch together a larger mesh, you use this to tell the renderer whether, and how exactly, you want to cover the whole mesh. E.g. if you use .5f or 2f as texture coordinates instead of 1f, textures will be stretched or shrunk accordingly.
+
+
+
+=== Connecting the Dots
+
+Next we turn these unrelated coordinates into *triangles*: We define the order in which each triangle is constructed. Think of these indexes as coming in groups of three. Each group of indexes describes one triangle. If the corners are identical, you can (and should!) reuse an index for several triangles. 
+
+
+Remember that you must specify the vertices counter-clockwise. 
+
+
+[source,java]
+----
+int [] indexes = { 2,0,1, 1,3,2 };
+----
+This syntax means:
+
+
+*  The indices 0,1,2,3 stand for the four vertices that you specified for the quad in `vertices[]`.
+*  The 2,0,1 triangle starts at top left, continues bottom left, and ends at bottom right.
+*  The 1,3,2 triangle start at bottom right, continues top right, and ends at top left.
+
+[source]
+----
+2\2--3
+| \  | Counter-clockwise
+|  \ |
+0--1\1
+----
+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 };`.) 
+
+
+<<spatial#,Spatial>>`FaceCullMode.Back`“
+
+
+
+=== Setting the Mesh Buffer
+
+You store the Mesh data in a buffer.
+
+
+.  Using `com.jme3.util.BufferUtils`, we create three buffers for the three types of information we have:
+**  vertex coordinates,
+**  texture coordinates,
+**  indices.
+
+.  We assign the data to the appropriate type of buffer inside the `Mesh` object. The three buffer types (`Position`, `TextCoord`, `Index`) are taken from an enum in `com.jme3.scene.VertexBuffer.Type`.
+.  The integer parameter describes the number of components of the values. Vertex postions are 3 float values, texture coordinates are 2 float values, and the indices are 3 ints representing 3 vertices in a triangle.
+.  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));
+mesh.setBuffer(Type.TexCoord, 2, BufferUtils.createFloatBuffer(texCoord));
+mesh.setBuffer(Type.Index,    3, BufferUtils.createIntBuffer(indexes));
+mesh.updateBound();
+----
+Our Mesh is ready! Now we want to see it.
+
+
+
+== Using the Mesh in a Scene
+
+We create a `com.jme3.scene.Geometry` and `com.jme3.material.Material`from our `mesh`, apply a simple color material to it, and attach it to the rootNode to make it appear in the scene.
+
+
+[source,java]
+----
+Geometry geo = new Geometry("OurMesh", mesh); // using our custom mesh object
+Material mat = new Material(assetManager, 
+    "Common/MatDefs/Misc/Unshaded.j3md");
+mat.setColor("Color", ColorRGBA.Blue);
+geo.setMaterial(mat);
+rootNode.attachChild(geo);
+----
+Library for assetManager?
+Ta-daa!
+
+
+
+== Using a Quad instead
+
+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
+Geometry geo = new Geometry("OurQuad", quad); // using Quad object
+Material mat = new Material(assetManager, 
+    "Common/MatDefs/Misc/Unshaded.j3md");
+mat.setColor("Color", ColorRGBA.Blue);
+geo.setMaterial(mat);
+rootNode.attachChild(geo);
+----
+If you want to change the Textures Coordinates, in order to change the scale of the texture, use :
+
+
+[source,java]
+----
+Quad quad = new Quad(1,1);
+quad.scaleTextureCoordinates(new Vector2f(width , height));
+----
+
+== Dynamic Meshes
+
+If you are modifying a mesh dynamically in a way which changes the model's bounds, you need to update it:
+
+
+.  Call `updateBound()` on the mesh object, and then 
+.  call `updateModelBound()` on the Geometry object containing the mesh. 
+
+The updateModelBound() method warns you about not usually needing to use it, but that can be ignored in this special case.
+
+
+_N.B.: This does not work on TerrainQuad.  Please use the TerrainQuad.adjustHeight() function to edit the TerrainQuad mesh instead.  Additionally, if you want to use collisions on them afterwards, you need to call TerrainPatch.getMesh().createCollisionData(); to update the collision data, else it will collide with what seems to be the old mesh. _
+
+
+
+== Optional Mesh Features
+
+There are more vertex buffers in a Mesh than the three shown above. For an overview, see also <<mesh#,mesh>>.
+
+
+
+=== Example: Vertex Colors
+
+Vertex coloring is a simple way of coloring meshes. Instead of just assigning one solid color, each vertex (corner) has a color assigned. The faces between the vertices are then colored with a gradient. For this demo, you can use the same mesh `mesh` object that you defined above.
+
+
+[source,java]
+----Geometry geo = new Geometry ("ColoredMesh", mesh); // using the custom mesh
+Material matVC = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+matVC.setBoolean("VertexColor", true);----
+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;----
+
+*  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];
+----
+**  Tip: If your mesh has a different number of vertices, you would write: 
+[source,java]
+----float[] colorArray = new float[yourVertexCount * 4]----
+
+
+Loop over the colorArray buffer to quickly set some RGBA value for each vertex. As usual, RGBA color values range from 0.0f to 1.0f. *Note that the color values in this example are arbitrarily chosen.* It's just a quick loop to give every vertex a different RGBA value (a purplish gray, purple, a greenish gray, green, see screenshot), without writing too much code. For your own mesh, you'd assign meaningful values for the color buffer depending on which color you want your mesh to have.
+
+
+[source,java]
+----
+// note: the red and green values are arbitray in this example
+for(int i = 0; i < 4; i++){
+   // Red value (is increased by .2 on each next vertex here)
+   colorArray[colorIndex++]= 0.1f+(.2f*i);
+   // Green value (is reduced by .2 on each next vertex)
+   colorArray[colorIndex++]= 0.9f-(0.2f*i);
+   // Blue value (remains the same in our case)
+   colorArray[colorIndex++]= 0.5f;
+   // Alpha value (no transparency set here)
+   colorArray[colorIndex++]= 1.0f;
+}----
+Next, set the color buffer. An RGBA color value contains four float components, thus the parameter `4`.
+
+
+[source,java]
+----mesh.setBuffer(Type.Color, 4, colorArray);
+geo.setMaterial(matVC);
+----
+When you run this code, you see a gradient color extending from each vertex.
+
+
+
+=== Example: Using Meshes With Lighting.j3md
+
+The previous examples used the mesh together with the `Unshaded.j3md` material. If you want to use the mesh with a Phong illuminated material (such as `Lighting.j3md`), the mesh must include information about its Normals. (Normal Vectors encode in which direction a mesh polygon is facing, which is important for calculating light and shadow!)
+
+
+[source,java]
+----
+float[] normals = new float[12];
+normals = new float[]{0,0,1, 0,0,1, 0,0,1, 0,0,1};
+mesh.setBuffer(Type.Normal, 3, BufferUtils.createFloatBuffer(normals));
+----
+You need to specify as many normals as the polygon has vertices. For a flat quad, the four normals point in the same direction. In this case, the direction is the Z unit vector (0,0,1), this means our quad is facing the camera. 
+
+
+If the mesh is more complex or rounded, calculate cross products of neighbouring vertices to identify normal vectors!
+
+
+
+=== Example: Point Mode
+
+Additionally to coloring the faces as just described, you can hide the faces and show only the vertices as colored corner points. 
+
+
+[source,java]
+----Geometry coloredMesh = new Geometry ("ColoredMesh", cMesh);
+...
+mesh.setMode(Mesh.Mode.Points);
+mesh.setPointSize(10f);
+mesh.updateBound();
+mesh.setStatic();
+Geometry points = new Geometry("Points", mesh);
+points.setMaterial(mat);
+rootNode.attachChild(points);
+rootNode.attachChild(geo);
+----
+This will result in a 10 px dot being rendered for each of the four vertices. The dot has the vertex color you specified above. The Quad's faces are not rendered at all in this mode. You can use this to visualize a special debugging or editing mode in your game.
+
+
+
+== Debugging Tip: Culling
+
+By default, jME3 optimizes a mesh by “backface culling, this means not drawing the inside. It determines the side of a triangle by the order of the vertices: The frontface is the face where the vertices are specified counter-clockwise.
+
+
+This means for you that, by default, your custom mesh is invisible when seen from “behind or from the inside. This may not be a problem, typically this is even intended, because it's faster. The player will not look at the inside of most things anyway. For example, if your custom mesh is a closed polyhedron, or a flat wallpaper-like object, then rendering the backfaces (the inside of the pillar, the back of the painting, etc) would indeed be a waste of resources.
+
+
+In case however that your usecase requires the backfaces be visible, you have two options:
+
+
+*  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 };----
+'''
+
+See also: 
+
+
+*  <<jme3/advanced/spatial#,Spatial>> – contains more info about how to debug custom meshes (that do not render as expected) by changing the default culling behaviour.
+*  <<jme3/advanced/mesh#,Mesh>> – more details about advanced Mesh properties
+<tags><tag target="spatial" /><tag target="node" /><tag target="mesh" /><tag target="geometry" /><tag target="scenegraph" /></tags>

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

@@ -0,0 +1,248 @@
+
+
+= Debugging
+
+When you deal with complex game engine features like animations or physics it is handy to get feedback from the engine how it interpreted the current state. Is the physical object's collision shape really where you think it is? Is the skeleton of the animated character moving like you think it should? This document shows you how to activate visual debug aides.
+
+
+What if you just want to quickly write code that loads models and brings them in their start position? You may not want to hunt for a sample model, convert it, add lights, and load materials. Instead you use “hasslefree simple shapes, and a “hasslefree unshaded material or wireframe: No model, no light source, no materials are needed to see them in your test scene. 
+
+
+If you ever have problems with objects appearing in the wrong spot, with the wrong scale, or wrong orientation, simply attach debug shapes to your scene to have a point of reference in 3D space – just like a giant ruler. If your code positions the debug shapes correctly, but models remain invisible when you apply the same code to them, you know that the problem must be either the model (where is its origin coordinate?), or the light (too dark? too bright? missing?), or the model's material (missing?) – and not the positioning code.
+
+
+Here are some different debug shapes: 
+
+
+
+image::jme3/advanced/debug-shapes.png[debug-shapes.png,with="600",height="220",align="center"]
+
+
+
+
+== Debug Shapes
+
+
+=== Coordinate Axes
+
+The coordinate axes (com.jme3.scene.debug.Arrow) help you see the cardinal directions (X,Y,Z) from their center point. Scale the arrows to use them as a “ruler for a certain length. 
+
+
+[source,java]
+----
+private void attachCoordinateAxes(Vector3f pos){
+  Arrow arrow = new Arrow(Vector3f.UNIT_X);
+  arrow.setLineWidth(4); // make arrow thicker
+  putShape(arrow, ColorRGBA.Red).setLocalTranslation(pos);
+
+  arrow = new Arrow(Vector3f.UNIT_Y);
+  arrow.setLineWidth(4); // make arrow thicker
+  putShape(arrow, ColorRGBA.Green).setLocalTranslation(pos);
+
+  arrow = new Arrow(Vector3f.UNIT_Z);
+  arrow.setLineWidth(4); // make arrow thicker
+  putShape(arrow, ColorRGBA.Blue).setLocalTranslation(pos);
+}
+
+private Geometry putShape(Mesh shape, ColorRGBA color){
+  Geometry g = new Geometry("coordinate axis", shape);
+  Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+  mat.getAdditionalRenderState().setWireframe(true);
+  mat.setColor("Color", color);
+  g.setMaterial(mat);
+  rootNode.attachChild(g);
+  return g;
+}----
+
+=== Wireframe Grid
+
+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){
+  Geometry g = new Geometry("wireframe grid", new Grid(size, size, 0.2f) );
+  Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+  mat.getAdditionalRenderState().setWireframe(true);
+  mat.setColor("Color", color);
+  g.setMaterial(mat);
+  g.center().move(pos);
+  rootNode.attachChild(g);
+  return g;
+}----
+
+=== Wireframe Cube
+
+Use a wireframe cube (com.jme3.scene.debug.WireBox) as a stand-in object to see whether your code scales, positions, or orients, loaded models right.
+
+
+[source,java]
+----
+public Geometry attachWireBox(Vector3f pos, float size, ColorRGBA color){
+  Geometry g = new Geometry("wireframe cube", new WireBox(size, size, size));
+  Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+  mat.getAdditionalRenderState().setWireframe(true);
+  mat.setColor("Color", color);
+  g.setMaterial(mat);
+  g.setLocalTranslation(pos);
+  rootNode.attachChild(g);
+  return g;
+}----
+
+=== Wireframe Sphere
+
+Use a wireframe sphere (com.jme3.scene.debug.WireSphere) as a stand-in object to see whether your code scales, positions, or orients, loaded models right.
+
+
+[source,java]
+----
+private Geometry attachWireSphere(Vector3f pos, float size, ColorRGBA color){
+  Geometry g = new Geometry("wireframe sphere", new WireSphere(size));
+  Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+  mat.getAdditionalRenderState().setWireframe(true);
+  mat.setColor("Color", color);
+  g.setMaterial(mat);
+  g.setLocalTranslation(pos);
+  rootNode.attachChild(g);
+  return g;
+}----
+
+== Wireframe for Physics
+
+You can display a wireframe of the (usually invisible) collision shape around all physical objects. Use this for debugging when analyzing unexpected behaviour. Does not work with DETACHED physics, please switch to PARALLEL or SEQUENTIAL for debugging.
+
+
+[source,java]
+----physicsSpace.enableDebug(assetManager);----
+With debugging enabled, colors are used to indicate various types of physical objects:
+
+
+*  A magenta wire mesh indicates an active rigid body.
+*  A blue wire mesh indicates a rigid body which is either new or inactive.
+*  A yellow wire mesh indicates a ghost.
+*  Two green arrows indicate a joint.
+*  A pink wire mesh indicates a character.
+
+
+== Wireframe for Animations
+
+Making the skeleton visible inside animated models can be handy for debugging animations. The `control` object is an AnimControl, `player` is the loaded model.
+
+
+[source,java]
+----
+     SkeletonDebugger skeletonDebug = 
+         new SkeletonDebugger("skeleton", control.getSkeleton());
+     Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+     mat.setColor("Color", ColorRGBA.Green);
+     mat.getAdditionalRenderState().setDepthTest(false);
+     skeletonDebug.setMaterial(mat);
+     player.attachChild(skeletonDebug);----
+
+== Example: Toggle Wireframe on Model
+
+We assume that you have loaded a model with a material `mat`.
+
+
+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");----
+.  Now add the toggle action to the action listener 
+[source,java]
+----
+  private ActionListener actionListener = new ActionListener() {
+    @Override
+    public void onAction(String name, boolean pressed, float tpf) {
+      // toggle wireframe
+      if (name.equals("toggle wireframe") && !pressed) {
+        wireframe = !wireframe; // toggle boolean
+        mat.getAdditionalRenderState().setWireframe(wireframe); 
+      }
+      // else ... other input tests.
+    }
+  };----
+.  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() {
+    boolean wireframe = false; 
+    
+    @Override
+    public void onAction(String name, boolean pressed, float tpf) {
+      // toggle wireframe
+      if (name.equals("toggle wireframe") && !pressed) {
+        wireframe = !wireframe; // toggle boolean
+        rootNode.depthFirstTraversal(new SceneGraphVisitor() {
+          public void visit(Spatial spatial) {
+            if (spatial instanceof Geometry)
+              ((Geometry)spatial).getMaterial().getAdditionalRenderState().setWireframe(wireframe);
+          }
+        }); 
+      }
+      // else ... other input tests.
+    }
+  };----
+
+TIP :: To set the line width of wireframe display, use mesh.setLineWidth(lineWidth). Default line width is 1.
+
+
+
+== Example: Toggle Wireframe on the scene
+
+To display the wireframe of the entire scene instead on one material at a time, first create the following Scene Processor
+
+
+[source,java]
+----public class WireProcessor implements SceneProcessor {    
+    
+    RenderManager renderManager;
+    Material wireMaterial;
+
+    public WireProcessor(AssetManager assetManager) {
+        wireMaterial = new Material(assetManager, "/Common/MatDefs/Misc/Unshaded.j3md");
+        wireMaterial.setColor("Color", ColorRGBA.Blue);
+        wireMaterial.getAdditionalRenderState().setWireframe(true);
+    }
+    
+    public void initialize(RenderManager rm, ViewPort vp) {
+        renderManager = rm;
+    }
+
+    public void reshape(ViewPort vp, int w, int h) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
+
+    public boolean isInitialized() {
+        return renderManager != null;
+    }
+
+    public void preFrame(float tpf) {        
+    }
+
+    public void postQueue(RenderQueue rq) {
+        renderManager.setForcedMaterial(wireMaterial);
+    }
+
+    public void postFrame(FrameBuffer out) {
+        renderManager.setForcedMaterial(null);
+    }
+
+    public void cleanup() {
+        renderManager.setForcedMaterial(null);
+    }
+    
+}----
+Then attach the scene processor to the +++<abbr title="Graphical User Interface">GUI</abbr>+++ Viewport.
+
+
+[source,java]
+----getViewPort().addProcessor(new WireProcessor());----
+
+== See also
+
+*  <<jme3/advanced/spatial#,Spatial>> – if you can't see certain spatials, you can modify the culling behaviour to identify problems (such as inside-out custom meshes)

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

@@ -0,0 +1,274 @@
+
+
+= jME3 Special Effects Overview
+
+jME3 supports several types of special effects: Post-Processor Filters, SceneProcessors, and Particle Emitters (also known as particle systems). This list contains screenshots and links to sample code that demonstrates how to add the effect to a scene.
+
+
+
+== Sample Code
+
+*  There is one `com.jme3.effect.ParticleEmitter` class for all Particle Systems. 
+*  There is one `com.jme3.post.FilterPostProcessor` class and several `com.jme3.post.filters.*` classes (all Filters have `*Filter` in their names). 
+*  There are several `SceneProcessor` classes in various packages, including e.g. `com.jme3.shadow.*` and `com.jme3.water.*` (SceneProcessor have `*Processor` or `*Renderer` in their names).
+
+
+=== Particle Emitter
+
+[source,java]
+----
+public class MyGame extends SimpleApplication {
+  public void simpleInitApp() {
+    ParticleEmitter pm = new ParticleEmitter("my particle effect", Type.Triangle, 60);
+    Material pmMat = new Material(assetManager, "Common/MatDefs/Misc/Particle.j3md");
+    pmMat.setTexture("Texture", assetManager.loadTexture("Effects/spark.png"));
+    pm.setMaterial(pmMat);
+    pm.setImagesX(1);
+    pm.setImagesY(1);
+    rootNode.attachChild(pm); // attach one or more emitters to any node
+  }
+}
+----
+
+=== Scene Processor
+
+[source,java]
+----
+public class MyGame extends SimpleApplication {
+    private BasicShadowRenderer bsr;
+    
+    public void simpleInitApp() {
+        bsr = new BasicShadowRenderer(assetManager, 1024);
+        bsr.setDirection(new Vector3f(.3f, -0.5f, -0.5f));
+        viewPort.addProcessor(bsr); // add one or more sceneprocessor to viewport
+    }
+----
+
+=== Post-Processor Filter
+
+[source,java]
+----
+public class MyGame extends SimpleApplication {
+    private FilterPostProcessor fpp; // one FilterPostProcessor per app
+    private SomeFilter sf;           // one or more Filters per app
+    
+    public void simpleInitApp() {
+        fpp = new FilterPostProcessor(assetManager);
+        viewPort.addProcessor(fpp); // add one FilterPostProcessor to viewPort
+
+        sf = new SomeFilter();
+        fpp.addFilter(sf);  // add one or more Filters to FilterPostProcessor
+    }
+----
+
+== Water
+
+
+image::jme3/advanced/water-post.png[water-post.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/water.png[water.png,with="150",height="100",align="right"]
+
+The jMonkeyEngine's <<jme3/advanced/water#,&quot;SeaMonkey&quot; WaterFilter>> simulates ocean waves, foam, including cool underwater caustics. 
+Use the SimpleWaterProcessor (SceneProcessor) for small, limited bodies of water, such as puddles, drinking troughs, pools, fountains.
+
+
+See also the link:http://jmonkeyengine.org/2011/01/15/new-advanced-water-effect-for-jmonkeyengine-3[Rendering Water as Post-Process Effect] announcement with video.
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/water/TestSceneWater.java[jme3/src/test/jme3test/water/TestSceneWater.java] – SimpleWaterProcessor (SceneProcessor)
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/water/TestSimpleWater.java[jme3/src/test/jme3test/water/TestSimpleWater.java] – SimpleWaterProcessor (SceneProcessor)
+
+
+image::jme3/advanced/water-reflection-muddy.png[water-reflection-muddy.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/underwater2.jpg[underwater2.jpg,with="150",height="100",align="right"]
+
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/water/TestPostWater.java[jme3/src/test/jme3test/water/TestPostWater.java] – WaterFilter
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/water/TestPostWaterLake.java[jme3/src/test/jme3test/water/TestPostWaterLake.java] – WaterFilter
+
+
+== Environment Effects
+
+
+=== Depth of Field Blur
+
+
+image::jme3/advanced/dof-blur.png[dof-blur.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/light-scattering-filter.png[light-scattering-filter.png,with="150",height="100",align="right"]
+
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestDepthOfField.java[jme3/src/test/jme3test/post/TestDepthOfField.java] – DepthOfFieldFilter
+
+
+=== Fog
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestFog.java[jme3/src/test/jme3test/post/TestFog.java] – FogFilter
+
+
+=== Light Scattering
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestLightScattering.java[jme3/src/test/jme3test/post/TestLightScattering.java] – LightScatteringFilter
+
+
+=== Vegetation
+
+*  Contribution: <<jme3/contributions/vegetationsystem/grass#,Grass System>>
+*  Contribution: link:http://jmonkeyengine.org/groups/user-code-projects/forum/topic/generating-vegetation-paged-geometry-style/[Trees (WIP)]
+
+
+== Light and Shadows
+
+
+image::jme3/advanced/tanlglow1.png[tanlglow1.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/shadow-sponza-ssao.png[shadow-sponza-ssao.png,with="150",height="100",align="right"]
+
+
+
+
+=== Bloom and Glow
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestBloom.java[jme3/src/test/jme3test/post/TestBloom.java]
+*  More details: <<jme3/advanced/bloom_and_glow#,Bloom and Glow>> – BloomFilter
+
+
+=== Light
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestSimpleLighting.java[jme3/src/test/jme3test/light/TestSimpleLighting.java] – DirectionalLight, PointLight
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestLightRadius.java[jme3/src/test/jme3test/light/TestLightRadius.java] – DirectionalLight, PointLight
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestManyLights.java[jme3/src/test/jme3test/light/TestManyLights.java] – .j3o scene
+*  More details: <<jme3/advanced/light_and_shadow#,Light and Shadow>>
+
+
+image::jme3/advanced/shadow.png[shadow.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/light-sources.png[light-sources.png,with="150",height="100",align="right"]
+
+
+
+
+=== Shadow
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestShadow.java[jme3/src/test/jme3test/light/TestShadow.java] – BasicShadowRenderer (SceneProcessor)
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestPssmShadow.java[jme3/src/test/jme3test/light/TestPssmShadow.java] – PssmShadowRenderer (SceneProcessor), also known as Parallel-Split Shadow Mapping (PSSM).
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestSSAO.java[jme3/src/test/jme3test/post/TestSSAO.java], link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestSSAO2.java[jme3/src/test/jme3test/post/TestSSAO2.java] – SSAOFilter, also known as Screen-Space Ambient Occlusion shadows (SSOA).
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestTransparentSSAO.java[jme3/src/test/jme3test/post/TestTransparentSSAO.java] – SSAOFilter, also known as Screen-Space Ambient Occlusion shadows (SSOA), plus transparancy
+*  More details: <<jme3/advanced/light_and_shadow#,Light and Shadow>>
+
+
+== Special: Glass, Metal, Dissolve, Toon
+
+
+image::jme3/advanced/toon-dino.png[toon-dino.png,with="150",height="100",align="right"]
+
+
+
+
+=== Toon Effect
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestCartoonEdge.java[jme3/src/test/jme3test/post/TestCartoonEdge.java] – CartoonEdgeFilter
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestTransparentCartoonEdge.java[jme3/src/test/jme3test/post/TestTransparentCartoonEdge.java] – CartoonEdgeFilter
+
+
+=== Fade in / Fade out
+
+*  <<jme3/advanced/fade#,Fade>> – FadeFilter
+
+
+=== User Contributed
+
+
+image::jme3/advanced/shaderblow_light1.jpg[shaderblow_light1.jpg,with="78",height="150",align="right"]
+
+image::jme3/advanced/shaderblow_glass.jpg[shaderblow_glass.jpg,with="80",height="150",align="right"]
+
+image::jme3/advanced/shaderblow_matcap.jpg[shaderblow_matcap.jpg,with="150",height="150",align="right"]
+
+image::jme3/advanced/shaderblow_light2.jpg[shaderblow_light2.jpg,with="66",height="150",align="right"]
+
+
+
+<<sdk/plugin/shaderblow#,ShaderBlow - GLSL Shader Library>>
+
+
+*  LightBlow Shader – blend material texture maps
+*  FakeParticleBlow Shader – jet, fire effect
+*  ToonBlow Shader – Toon Shading, toon edges 
+*  Dissolve Shader – Scifi teleportation/dissolve effect
+*  MatCap Shader – Gold, metals, glass, toons…!
+*  Glass Shader – Glass
+*  Force Shield Shader – Scifi impact-on-force-field effect
+*  SimpleSprite Shader – Animated textures
+*  SimpleSpriteParticle Shader – Sprite library
+*  MovingTexture Shader – Animated cloud/mist texture
+*  SoftParticles Shader – Fire, clouds, smoke etc
+*  Displace Shader – Deformation effect: Ripple, wave, pulse, swell!
+
+Thanks for your awesome contributions! Keep them coming!
+
+
+
+== Particle Emitters: Explosions, Fire, Smoke
+
+
+image::jme3/advanced/explosion-5.png[explosion-5.png,with="150",height="100",align="right"]
+
+image::jme3/advanced/particle.png[particle.png,with="150",height="100",align="right"]
+
+<<particle_emitters#,Particle emitter effects>> are highly configurable and can have any texture. They can simulate smoke, dust, leaves, meteors, snowflakes, mosquitos, fire, explosions, clusters, embers, sparks…
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/effect/TestExplosionEffect.java[jme3/src/test/jme3test/effect/TestExplosionEffect.java] – debris, flame, flash, shockwave, smoke, sparks
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/effect/TestPointSprite.java[jme3/src/test/jme3test/effect/TestPointSprite.java] – cluster of points 
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/effect/TestMovingParticle.java[jme3/src/test/jme3test/effect/TestMovingParticle.java] – dust, smoke
+'''
+
+
+=== Creating your own Filters
+
+Here is an extract taken from @nehon in the forum thread (link:http://hub.jmonkeyengine.org/forum/topic/how-exactly-do-filters-work/[http://hub.jmonkeyengine.org/forum/topic/how-exactly-do-filters-work/])
+
+
+The methods are called in this order (pretty much the same flow as processors):
+- initFilter() is called once when the FilterPostPorcessor is initialized or when the filter is added to the processor and this one as already been initialized.
+
+
+for each frame the methods are called in that sequence :
+- preFrame() occurs before anything happens
+- postQueue() occcurs once the queues have been populated (there is one queue per bucket and 2 additional queues for the shadows, casters and recievers). Note that geometries in the queues are the one in the view frustum.
+- postFrame occurs once the main frame has been rendered (the back buffer)
+
+
+Those methods are optional in a filter, they are only there if you want to hook in the rendering process.
+
+
+The material variable is here for convenience. You have a getMaterial method that returns the material that’s gonna be used to render the full screen quad. It just happened that in every implementation I had a material attribute in all my sub-classes, so I just put it back in the abstract class. Most of the time getMaterial returns this attribute.
+
+
+Forced-technique can be any technique really, they are more related with the material system than to the filters but anyway. When you use a forced technique the renderer tries to select it on the material of each geometry, if the technique does not exists for the material the geometry is not rendered.
+You assume well about the SSAO filer, the normal of the scene are rendered to a texture in a pre pass.
+
+
+Passes : these are filters in filters in a way. First they are a convenient way to initialize a FrameBuffer and the associated textures it needs, then you can use them for what ever you want.
+For example, a Pass can be (as in the SSAO filter) an extra render of the scene with a forced technique, and you have to handle the render yourself in the postQueue method.
+It can be a post pass to do after the main filter has been rendered to screen (for example an additional blur pass used in SSAO again). You have a list of passes called postRenderPass in the Filter abstract class. If you add a pass to this list, it’ll be automatically rendered by the FilterPostProcessor during the filter chain.
+
+
+The bloom Filter does an intensive use of passes.
+
+
+Filters in a nutshell.
+
+'''
+
+See also:
+
+
+*  <<particle_emitters#,Particle Emitters>>
+*  <<bloom_and_glow#,Bloom and Glow>>
+*  link:http://www.smashingmagazine.com/2008/08/07/50-photoshop-tutorials-for-sky-and-space-effects/[Photoshop Tutorial for Sky and space effects (article)]
+<tags><tag target="documentation" /><tag target="effect" /><tag target="light" /><tag target="water" /></tags>

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

@@ -0,0 +1,78 @@
+
+
+= Endless Terrain
+
+link:http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072[http://hub.jmonkeyengine.org/forum/topic/design-question-terrain/#post-262072]
+
+
+TerrainGrid is DEPRECATED.
+
+
+TerrainGrid is an extension built on top of the TerraMonkey tools like TerrainQuad and HeightMap, that provides “infinite Terrain paging routines.  +
+
+Thanks to Gábor (@anthyon) and Brent (@sploreg) for this contribution!
+
+
+
+== Sample Code
+
+The classes with source code can be found in the org.jme3.terrain.geomipmapping and org.jme3.terrain.heightmap packages. Also there are 3 tests prepared in the jme3test.terrain package:
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/terrain/TerrainGridTest.java[TerrainGridTest.java]: uses an ImageBasedHeightMapGrid instance to load the tiles
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/terrain/TerrainFractalGridTest.java[TerrainFractalGridTest.java]: makes use of the FractalHeightMapGrid class, and generates a terrain from noise
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/terrain/TerrainGridAlphaMapTest.java[TerrainGridAlphaMapTest.java]: shows how to use TerrainGridListener to change the material of the tiles
+
+
+== Specification
+
+TerrainGrid is made up of the TerrainGrid class, and the HeightMapGrid and TerrainGridListener interfaces.
+
+
+*  TerrainGrid is the central class of the system. It takes care for handling camera movement in LODUpdate, loading and unloading terrain tiles on demand, and notifying any registered listeners of changes.
+*  TerrainGridListener defines two events to listen to:
+**  gridMoved(Vector3f):  gets the new center as parameter after terrain update, so any objects can be added or removed as needed.
+**  Material tileLoaded(Material material, Vector3f cell): notifies the system about a tile being loaded. Parameters are a cloned value of the material added to the TerrainGrid, and the cell of the new tile. The system can change the material according to this information (eg. load required alphamaps, etc).
+
+
++
+
+Multiple listeners can be added to the TerrainGrid, they will be called in the order of addition, so it’s possible to have multiple changes to the material before completing the load of the tile.
++
+
+HeightMapGrid adds the possibility of loading terrain tiles on demand instead of having a simple height array. There’s no predefined way of how to store these tiles, it only takes care of loading one HeightMap object at given location at a time.
+
+
+
+== Motivation
+
+
+image::wp-uploads/2011/06/grid-tiles.jpg[grid-tiles.jpg,with="130",height="130",align="right"]
+
+After playing around with the terrain in jME3, soon comes the requirement of having larger explorable lands. Increasing the size of one TerrainQuad leads to more memory usage, while it will still be easy to reach the worlds boundaries. That’s why TerrainGrid was designed. It extends the TerraindQuad class and uses 4 HeightMaps (dark blue) as the four sub-quad. This means that a terrain of size 513 will use tiles of 257. Also an LRUCache is built into the terrain package, so surrounding tiles (green) can be pre-cached on a different thread, lowering the loading time. The quads are updated as the camera approaches the boundary of the light blue section.
+
+
+
+== Rationale
+
+The design of the TerrainGrid system was chosen carefully, so that minimal effort needs to be taken to switch from previous TerrainQuad uses. It has the same constructors with the small exception that instead of an array of heightmap it takes a HeightMapGrid instance. All other parameters are forwarded down to the underlying TerrainQuad system.
+There exist also two basic HeightMapGrid implementations:
+
+
+*  ImageBasedHeightMapGrid: uses a sequentially numbered, 16 bit grayscale heightmaps. The physical filename of these files can be generated through the Namer interface. When a tile cannot be found by the assetManager, an empty (all-zero) heightmap is created, and a warning is added to the log.
+*  FractalHeightMapGrid: uses a noise library to create a landscape on the fly. The shape of the terrain can be controlled by the various parameters and postfilters of the fractals. With the help of this grid implementation there’s no limitation – above of floating point precision limits – how far the camera can get. The tiles generated this way can be cached to the filesystem, for later modification. The FractalHeightMapGrid will always load from cache if a tile exists there!
+
+
+== Usage
+
+.   instantiate a TerrainGrid object
+.   set material, listeners, translation, scale, etc.
+.   add a LODControl instance to the object
+.   call initialize with the camera location
+.   (optional) add it to the physicsSpace as you would a TerrainQuad
+
+Further information about terrain and TerrainQuad can be found in the wiki at:
+
+
+*  link:http://jmonkeyengine.org/wiki/doku.php/jme3:beginner:hello_terrain[http://jmonkeyengine.org/wiki/doku.php/jme3:beginner:hello_terrain] and
+*  link:http://jmonkeyengine.org/wiki/doku.php/jme3:advanced:terrain[http://jmonkeyengine.org/wiki/doku.php/jme3:advanced:terrain]

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

@@ -0,0 +1,36 @@
+
+
+= Fade-in / Fade-out Effect
+
+You can use a fade in/fade out effect to make smooth transitions, for example between game levels. The effect fades in from black to the initialized scene, or fades out from the scene to black.
+The effect uses com.jme3.post.FilterPostProcessor and com.jme3.post.filters.FadeFilter.
+
+
+
+== Setting up
+
+.  Create one FilterPostProcessor object per application.
+.  Create a FadeFilter object.
+.  Give the FadeFilter constructor the fade duration in seconds as parameter. If you use the parameter-less constructor, the duration is 1 sec by default.
+.  Add the FadeFilter to the FilterPostProcessor.
+.  Add the FilterPostProcessor to the default viewPort.
+
+[source,java]
+----
+private FilterPostProcessor fpp;
+private FadeFilter fade;
+public void simpleInitApp() {
+  ...
+  fpp = new FilterPostProcessor(assetManager);
+  fade = new FadeFilter(2); // e.g. 2 seconds
+  fpp.addFilter(fade);
+  viewPort.addProcessor(fpp);
+  ...
+}
+----
+
+== Fading in and out
+
+Now call the `fade.fadeIn()` and `fade.fadeOut()` methods to trigger the effect.
+You can also change the fade duration using `fade.setDuration()`.
+

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

@@ -0,0 +1,59 @@
+
+
+= jME3 Headless Server
+
+When adding multiplayer to your game, you may find that your server needs to know about game state (e.g. where are players, objects? Was that a direct hit? etc.) You can code all this up yourself, but there's an easier way. 
+
+
+It's very easy to change your current (client) game to function as a server as well.
+
+
+
+== What Does Headless Mean?
+
+A headless server…
+
+
+*  does not display any output – no window opens, no audio plays, no graphics are rendered.
+*  ignores all input – no input handling.
+*  keeps game state – you can attach to, transform, and save the rootNode, although the scene is not displayed.
+*  calls the `simpleUpdate()` loop – you can run tests and trigger events as usual.
+
+
+== Client Code
+
+First, let's take a look at the default way of creating a new game (in its simplest form):
+
+
+[source,java]
+----
+public static void main(String[] args) {
+  Application app = new Main();
+  app.start();
+}----
+
+== Headless Server Code
+
+Now, with a simple change you can start your game in Headless mode. This means that all input and audio/visual output will be ignored. That's a good thing for a server.
+
+
+[source,java]
+----
+import com.jme3.system.JmeContext;
+import com.jme3.system.JmeContext.Type;
+
+public static void main(String[] args) {
+  Application app = new Main();
+  app.start(JmeContext.Type.Headless);
+}----
+
+== Next steps
+
+Okay, so you can now start your game in a headless 'server mode', where to go from here?
+
+
+*  Parse `String[] args` from the `main`-method to enable server mode on demand (e.g. start your server like `java -jar mygame.jar –server`.
+*  Integrate <<jme3/advanced/networking#,SpiderMonkey>>, to provide game updates to the server over a network.
+*  Only execute code that's needed. (E.g. place all rendering code inside an `if (servermode)`-block) (or `if (!servermode)` for the client).
+*  Add decent <<jme3/advanced/logging#,logging>> so your server actually makes sense.
+<tags><tag target="server" /><tag target="spidermonkey" /><tag target="headless" /><tag target="network" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,159 @@
+
+
+= Physical Hinges and Joints
+
+The jMonkeyEngine3 has built-in support for link:http://jbullet.advel.cz[jBullet physics] via the `com.jme3.bullet` package.
+
+
+Game Physics are not only employed to calculate collisions, but they can also simulate hinges and joints. Think of pulley chains, shaky rope bridges, swinging pendulums, or (trap)door and chest hinges. Physics are a great addition to e.g. an action or puzzle game.
+
+
+In this example, we will create a pendulum. The joint is the (invisible) connection between the pendulum body and the hook. You will see that you can use what you learn from the simple pendulum and apply it to other joint/hinge objects (rope bridges, etc).
+
+
+
+== Sample Code
+
+*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/bullet/TestPhysicsHingeJoint.java[TestPhysicsHingeJoint.java]
+
+
+== Overview of this Physics Application
+
+.  Create a SimpleApplication with a <<jme3/advanced/physics#,BulletAppState>> 
+**  This gives us a PhysicsSpace for PhysicsControls
+
+.  For the pendulum, we use a Spatial with a PhysicsControl, and we apply physical forces to them.
+**  The parts of the “pendulum are Physics Control'ed Spatials with Collision Shapes. 
+**  We create a fixed `hookNode` and a dynamic `pendulumNode`. 
+
+.  We can “crank the handle and rotate the joint like a hinge, or we can let loose and expose the joints freely to gravity. 
+**  For physical forces we will use the method `joint.enableMotor();`
+
+
+
+== Creating a Fixed Node
+
+The hookNode is the fixed point from which the pendulum hangs. It has no mass. 
+
+
+[source,java]
+----
+Node hookNode=PhysicsTestHelper.createPhysicsTestNode(
+    assetManager, new BoxCollisionShape(new Vector3f( .1f, .1f, .1f)),0);
+hookNode.getControl(RigidBodyControl.class).setPhysicsLocation(new Vector3f(0f,0,0f));
+
+rootNode.attachChild(hookNode);
+getPhysicsSpace().add(hookNode);
+----
+For a rope bridge, there would be two fixed nodes where the bridge is attached to the mountainside.
+
+
+
+== Creating a Dynamic Node
+
+The pendulumNode is the dynamic part of the construction. It has a mass. 
+
+
+[source,java]
+----
+Node pendulumNode=PhysicsTestHelper.createPhysicsTestNode(
+    assetManager, new BoxCollisionShape(new Vector3f( .3f, .3f, .3f)),1);
+pendulumNode.getControl(RigidBodyControl.class).setPhysicsLocation(new Vector3f(0f,-1,0f));
+rootNode.attachChild(pendulumNode);
+getPhysicsSpace().add(pendulumNode);
+----
+For a rope bridge, each set of planks would be one dynamic node. 
+
+
+
+== Understanding DOF, Joints, and Hinges
+
+A PhysicsHingeJoint is an invisible connection between two nodes – here between the pendulum body and the hook. Why are hinges and joints represented by the same class? Hinges and joints have something in common: They constrain the _mechanical degree of freedom_ (DOF) of another object. 
+
+
+Consider a free falling, “unchained object in physical 3D space: It has 6 DOFs:
+
+
+*  It translates along 3 axes
+*  It rotates around 3 axes
+
+Now consider some examples of objects with joints:
+
+
+*  An individual chain link is free to spin and move around, but joined into a chain, the link's movement is restricted to stay with the surrounding links.
+*  A person's arm can rotate around some axes, but not around others. The shoulder joint allows one and restricts the other.
+*  A door hinge is one of the most restricted types of joint: It can only rotate around one axis. 
+
+You'll understand that, when creating any type of joint, it is important to correctly specify the DOFs that the joint restricts, and the DOFs that the joint allows. For the typical DOF of a <<ragdoll#,ragDoll>> character's limbs, jME even offers a special joint, `ConeJoint`.
+
+
+
+== Creating the Joint
+
+You create the HingeJoint after you have created the nodes that are to be chained together. In the code snippet you see that the HingeJoint constructor requires the two node objects. You also have to specify axes and pivots – they are the degrees of freedom that you just heard about.
+
+
+[source,java]
+----
+private HingeJoint joint;
+...
+  public void simpleInitApp() {
+    ...
+    // hookNode and pendulumNode are created here...
+    ...
+    
+    joint=new HingeJoint(hookNode.getControl(RigidBodyControl.class), // A
+                     pendulumNode.getControl(RigidBodyControl.class), // B
+                     new Vector3f(0f, 0f, 0f),  // pivot point local to A
+                     new Vector3f(0f, 1f, 0f),  // pivot point local to B 
+                     Vector3f.UNIT_Z,           // DoF Axis of A (Z axis)
+                     Vector3f.UNIT_Z  );        // DoF Axis of B (Z axis)
+----
+The pivot point's position will be at `(0,0,0)` in the global 3D space. In A's local space that is at `(0,0,0)` and in B's local space (remember B's position was set to `(0,-1,0)`) that is at `(0,1,0)`.
+
+
+Specify the following parameters for each joint:
+
+
+*  PhysicsControl A and B – the two nodes that are to be joined
+*  Vector3f pivot A and pivot B – coordinates of the attachment point relative to A and B
+**  The points typically lie on the surface of the PhysicsControl's Spatials, rarely in the middle.
+
+*  Vector3f axisA and axisB – around which axes each node is allowed to spin.
+**  In our example, we constrain the pendulum to swing only along the Z axis.
+
+
+Remember to add all joint objects to the physicsSpace, just like you would do with any physical objects.
+
+
+[source,java]
+----bulletAppState.getPhysicsSpace().add(joint);----
+*Tip:* If you want the joint to be visible, attach a geometry to the dynamic node, and translate it to its start position.
+
+
+
+== Apply Physical Forces
+
+You can apply forces to dynamic nodes (the ones that have a mass), and see how other joined (“chained) objects are dragged along. 
+
+
+Alternatively, you can also apply forces to the joint itself. In a game, you may want to spin an automatic revolving door, or slam a door closed in a spooky way, or dramatically open the lid of a treasure chest.
+
+
+The method to call on the joint is `enableMotor()`.
+
+
+[source,java]
+----joint.enableMotor(true, 1, .1f);
+joint.enableMotor(true, -1, .1f);----
+.  Switch the motor on by supplying `true`
+.  Specify the velocity with which the joint should rotate around the specified axis. 
+**  Use positive and negative numbers to change direction.
+
+.  Specify the impulse for this motor. Heavier masses need a bigger impulse to be moved.
+
+When you disable the motor, the chained nodes are exposed to gravity again:
+
+
+[source,java]
+----joint.enableMotor(false, 0, 0);----<tags><tag target="documentation" /><tag target="physics" /><tag target="joint" /></tags>

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

@@ -0,0 +1,164 @@
+
+
+= Head-Up Display (HUD)
+
+
+image::http///www.jmonkeyengine.com/wp-content/uploads/2010/10/grapplinghook.jpg[grapplinghook.jpg,with="256",height="192",align="right"]
+
+
+
+A HUD (Head-Up Display) is part of a game's visual user interface. It's an overlay that displays additional information as (typically) 2-dimensional text or icons on the screen, on top of the 3D scene. Not all games have, or need a HUD. To avoid breaking the immersion and cluttering the screen, only use a HUD if it is the only way to convey certain information.
+
+
+HUDs are used to supply players with essential information about the game state.
+
+
+*  Status: Score, minimap, points, stealth mode, …
+*  Resources: Ammunition, lives/health, time, …
+*  Vehicle instruments: Cockpit, speedometer, …
+*  Navigational aides: Crosshairs, mouse pointer or hand, …
+
+You have multiple options how to create HUDs.
+
+[cols="3", options="header"]
+|===
+
+a|Option
+a|Pros
+a|Cons
+
+a|Attach elements to default guiNode:
+a|Easy to learn. jMonkeyEngine built-in +++<abbr title="Application Programming Interface">API</abbr>+++ for attaching plain images and bitmap text.
+a|Only basic features. +
+You will have to write custom controls / buttons / effects if you need them.
+
+a|Use advanced <<nifty_gui#,Nifty GUI>> integration:
+a|Full-featured interactive user interface. +
+Includes buttons, effects, controls. +
+Supports XML and Java layouts.
+a|Steeper learning curve.
+
+a|Use user contributed +++<abbr title="Graphical User Interface">GUI</abbr>+++ libraries such as <<jme3/contributions/tonegodgui#,tonegodgui>> or link:http://hub.jmonkeyengine.org/t/lemur-api-documentation/27209[Lemur]:
+a|Both have many features that would be difficult to do with Nifty +
+Includes buttons, effects, controls. +
+New features are still being released 
+a|Are not necessarily guaranteed future updates, not as well documented
+
+|===
+
+Using the +++<abbr title="Graphical User Interface">GUI</abbr>+++ Node is the default approach in jme3 to create simple HUDs. If you just quickly want to display a line of text, or a simple icon on the screen, use the no-frills +++<abbr title="Graphical User Interface">GUI</abbr>+++ Node, it's easier.
+
+
+
+== Simple HUD: GUI Node
+
+You already know the `rootNode` that holds the 3-dimensional scene graph. jME3 also offers a 2-dimension (orthogonal) node, the `guiNode`. 
+
+
+This is how you use the guiNode for HUDs:
+
+
+*  Create a +++<abbr title="Graphical User Interface">GUI</abbr>+++ element: a BitmapText or Picture object.
+*  Attach the element to the guiNode. 
+*  Place the element in the orthogonal render queue using `setQueueBucket(Bucket.Gui)`. 
+
+The BitmapTexts and Pictures appear as 2 dimensional element on the screen.
+
+
++++<abbr title="Graphical User Interface">GUI</abbr>+++
+
+
+[source,java]
+----setDisplayStatView(false); setDisplayFps(false);----
+
+
+
+
+=== Displaying Pictures in the HUD
+
+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);
+pic.setWidth(settings.getWidth()/2);
+pic.setHeight(settings.getHeight()/2);
+pic.setPosition(settings.getWidth()/4, settings.getHeight()/4);
+guiNode.attachChild(pic);
+----
+When you set the last boolean in setImage() to true, the alpha channel of your image is rendered transparent/translucent.
+
+
+
+=== Displaying Text in the HUD
+
+You use `com.jme3.font.BitmapText` to display text on the screen. 
+
+
+[source,java]
+----
+BitmapText hudText = new BitmapText(guiFont, false);          
+hudText.setSize(guiFont.getCharSet().getRenderedSize());      // font size
+hudText.setColor(ColorRGBA.Blue);                             // font color
+hudText.setText("You can write any string here");             // the text
+hudText.setLocalTranslation(300, hudText.getLineHeight(), 0); // position
+guiNode.attachChild(hudText);
+----
+The BitmapFont object `guiFont` is a default font provided by SimpleApplication. Copy you own fonts as .fnt plus .png files into the `assets/Interface/Fonts` directory and load them like this:
+
+
+[source]
+----BitmapFont myFont = assetManager.loadFont("Interface/Fonts/Console.fnt");
+hudText = new BitmapText(myFont, false);----
+
+=== Positioning HUD Elements
+
+*  When positioning +++<abbr title="Graphical User Interface">GUI</abbr>+++ text and images in 2D, the *bottom left corner* of the screen is `(0f,0f)`, and the *top right corner* is at `(settings.getWidth(),settings.getHeight())`.
+*  If you have several 2D elements in the +++<abbr title="Graphical User Interface">GUI</abbr>+++ bucket that overlap, define their depth order by specifing a Z value. For example use `pic.move(x, y, -1)` to move the picture to the background, or `hudText.setLocalTranslation(x,y,1)` to move text to the foreground.
+*  Size and length values in the orthogonal render queue are treated like pixels. A 20*20-wu big quad is rendered 20 pixels wide.
+
+
+=== Displaying Geometries in the HUD
+
+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>+++
+
+
+
+=== Keeping the HUD Up-To-Date
+
+Use the update loop to keep the content up-to-date.
+
+
+[source,java]
+----public void simpleUpdate(float tpf) {
+  ...
+  hudText.setText("Score: " + score);
+  ...
+  picture.setImage(assetManager, "Interface/statechange.png", true);
+  ...
+}----
+
+== Advanced HUD: Nifty GUI
+
+The recommended approach to create HUDs is using <<nifty_gui#,Nifty GUI>>.
+
+
+.  Lay out the +++<abbr title="Graphical User Interface">GUI</abbr>+++ in one or several Nifty XML or Java files. 
+.  Write the controller classes in Java.
+.  Load the XML file with the controller object in your game's simpleInit() method.
+
+The advantage of Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ is that it is well integrated into jME and the jMonkeyEngine SDK, and that it offers all the features that you expect from a professional modern user interface. 
+
+
+For HUDs, you basically follow the same instructions as for creating a normal <<jme3/advanced/nifty_gui#,Nifty GUI>>, you just don't pause the game while the HUD is up.
+
+
+
+== See also
+
+*  <<jme3/external/fonts#,Fonts>>
+<tags><tag target="gui" /><tag target="display" /><tag target="documentation" /><tag target="hud" /></tags>

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

@@ -0,0 +1,312 @@
+
+
+= Input Handling
+
+Users interact with your jME3 application with different input devices – the mouse, the keyboard, or a joystick. To respond to inputs we use the `inputManager` object in `SimpleApplication`.
+
+
+This is how you add interaction to your game:
+
+
+.  For each action, choose the trigger(s) (a key or mouse click etc)
+.  For each action, add a trigger mapping to the inputManager
+.  Create at least one listener in SimpleApplication
+.  For each action, register its mappings to a listener
+.  Implement each action in the listener
+
+
+== Code Samples
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestControls.java[TestControls.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestJoystick.java[TestJoystick.java]
+
+
+== 1. Choose Trigger
+
+Choose one or several key/mouse events for the interaction. We use `KeyTrigger`, `MouseAxisTrigger`, `MouseButtonTrigger`, `JoyAxisTrigger` and `JoyButtonTrigger` constants from the `com.jme3.input.controls` package. 
+
+
+*Note:* The MouseAxis and JoyAxis triggers go along the X axis (right/left) or Y axis (up/down). These Triggers come with extra booleans for the negative half of the axis (left, down). Remember to write code that listens to the negative (true) and positive (false) axis!
+
+[cols="2", options="header"]
+|===
+
+a| Trigger 
+a| Code 
+
+a| Mouse button: Left Click 
+a| MouseButtonTrigger(MouseInput.BUTTON_LEFT) 
+
+a| Mouse button: Right Click 
+a| MouseButtonTrigger(MouseInput.BUTTON_RIGHT) 
+
+a| Mouse button: Middle Click 
+a| MouseButtonTrigger(MouseInput.BUTTON_MIDDLE) 
+
+a| Mouse movement: Right 
+a| MouseAxisTrigger(MouseInput.AXIS_X, true) 
+
+a| Mouse movement: Left 
+a| MouseAxisTrigger(MouseInput.AXIS_X, false)
+
+a| Mouse movement: Up 
+a| MouseAxisTrigger(MouseInput.AXIS_Y, true) 
+
+a| Mouse movement: Down 
+a| MouseAxisTrigger(MouseInput.AXIS_Y, false) 
+
+a| Mouse wheel: Up 
+a| MouseAxisTrigger(MouseInput.AXIS_WHEEL,false) 
+
+a| Mouse wheel: Down 
+a| MouseAxisTrigger(MouseInput.AXIS_WHEEL,true) 
+
+a| NumPad: 1, 2, 3, … 
+a| KeyTrigger(KeyInput.KEY_NUMPAD1) … 
+
+a| Keyboard: 1, 2 , 3, … 
+a| KeyTrigger(KeyInput.KEY_1) … 
+
+a| Keyboard: A, B, C, … 
+a| KeyTrigger(KeyInput.KEY_A) … 
+
+a| Keyboard: Spacebar 
+a| KeyTrigger(KeyInput.KEY_SPACE) 
+
+a| Keyboard: Shift 
+a| KeyTrigger(KeyInput.KEY_RSHIFT), +
+KeyTrigger(KeyInput.KEY_LSHIFT) 
+
+a| Keyboard: F1, F2, … 
+a| KeyTrigger(KeyInput.KEY_F1) … 
+
+a| Keyboard: Return, Enter 
+<a| KeyTrigger(KeyInput.KEY_RETURN), +
+KeyTrigger(KeyInput.KEY_NUMPADENTER)  
+
+a| Keyboard: PageUp, PageDown 
+a| KeyTrigger(KeyInput.KEY_PGUP), +
+KeyTrigger(KeyInput.KEY_PGDN) 
+
+a| Keyboard: Delete, Backspace 
+a| KeyTrigger(KeyInput.KEY_BACK), +
+KeyTrigger(KeyInput.KEY_DELETE) 
+
+a| Keyboard: Escape 
+a| KeyTrigger(KeyInput.KEY_ESCAPE) 
+
+a| Keyboard: Arrows 
+a| KeyTrigger(KeyInput.KEY_DOWN), +
+KeyTrigger(KeyInput.KEY_UP) +
+KeyTrigger(KeyInput.KEY_LEFT), KeyTrigger(KeyInput.KEY_RIGHT) 
+
+a| Joystick Button: 
+a| JoyButtonTrigger(0, JoyInput.AXIS_POV_X), +
+JoyButtonTrigger(0, JoyInput.AXIS_POV_Y) ? 
+
+a| Joystick Movement: Right 
+a| JoyAxisTrigger(0, JoyInput.AXIS_POV_X, true) 
+
+a| Joystick Movement: Left 
+a| JoyAxisTrigger(0, JoyInput.AXIS_POV_X, false) 
+
+a| Joystick Movement: Forward 
+a| JoyAxisTrigger(0, JoyInput.AXIS_POV_Z, true) 
+
+a| Joystick Movement: Backward
+a| JoyAxisTrigger(0, JoyInput.AXIS_POV_Z, false) 
+
+|===
+
+In your IDE, use code completion to quickly look up Trigger literals. In the jMonkeyEngine SDK for example, press ctrl-space or ctrl-/ after `KeyInput.|` to choose from the list of all keys.
+
+
+
+== 2. Remove Default Trigger Mappings
+
+[source]
+----inputManager.deleteMapping( SimpleApplication.INPUT_MAPPING_MEMORY );----[cols="3", options="header"]
+|===
+
+a|Default Mapping
+a|Key
+a|Description
+
+a|INPUT_MAPPING_HIDE_STATS
+a|F5
+a|Hides the statistics in the bottom left.
+
+a|INPUT_MAPPING_CAMERA_POS
+a|KEY_C
+a|Prints debug output about the camera.
+
+a|INPUT_MAPPING_MEMORY
+a|KEY_M
+a|Prints debug output for memory usage.
+
+a|INPUT_MAPPING_EXIT
+a|KEY_ESCAPE
+a|Closes the application by calling `stop();`. Typically you do not remove this, unless you replace it by another way of quitting gracefully.
+
+|===
+
+
+== 3. Add Custom Trigger Mapping
+
+When initializing the application, add a Mapping for each Trigger. 
+
+
+Give the mapping a meaningful name. The name should reflect the action, not the button/key (because buttons/keys can change). Here some examples:
+
+
+[source,java]
+----
+inputManager.addMapping("Pause Game", new KeyTrigger(KeyInput.KEY_P));
+inputManager.addMapping("Rotate",     new KeyTrigger(KeyInput.KEY_SPACE));
+...
+----
+There are cases where you may want to provide more then one trigger for one action. For example, some users prefer the WASD keys to navigate, while others prefer the arrow keys. Add several triggers for one mapping, by separating the Trigger objects with commas:
+
+
+[source,java]
+----
+inputManager.addMapping("Left",  new KeyTrigger(KeyInput.KEY_A), 
+                                 new KeyTrigger(KeyInput.KEY_LEFT)); // A and left arrow
+inputManager.addMapping("Right", new KeyTrigger(KeyInput.KEY_D), 
+                                 new KeyTrigger(KeyInput.KEY_RIGHT)); // D and right arrow
+                                 ...
+----
+
+== 4. Create Listeners
+
+The jME3 input manager supports two types of event listeners for inputs: AnalogListener and ActionListener. You can use one or both listeners in the same application. Add one or both of the following code snippets to your main SimpleApplication-based class to activate the listeners.
+
+
+*Note:* The two input listeners do not know, and do not care, which actual key was pressed. They only know which _named input mapping_ was triggered. 
+
+
+
+=== ActionListener
+
+`com.jme3.input.controls.ActionListener`
+
+
+*  Use for absolute “button pressed or released?, “on or off? actions. 
+**  Examples: Pause/unpause, a rifle or revolver shot, jump, click to select.
+
+*  JME gives you access to:
+**  The mapping name of the triggered action.
+**  A boolean whether the trigger is still pressed or has just been released.
+**  A float of the current time-per-frame as timing factor
+
+*  
+
+[source,java]
+----
+private ActionListener actionListener = new ActionListener() {
+  public void onAction(String name, boolean keyPressed, float tpf) {
+     /** TODO: test for mapping names and implement actions */
+  }
+};----
+
+=== AnalogListener
+
+`com.jme3.input.controls.AnalogListener`
+
+
+*  Use for continuous and gradual actions.
+**  Examples: Walk, run, rotate, accelerate vehicle, strafe, (semi-)automatic weapon shot
+
+*  JME gives you access to:
+**  The mapping name of the triggered action.
+**  A gradual float value between how long the trigger has been pressed.
+**  A float of the current time-per-frame as timing factor
+
+
+[source,java]
+----
+private AnalogListener analogListener = new AnalogListener() {
+  public void onAnalog(String name, float keyPressed, float tpf) {
+     /** TODO: test for mapping names and implement actions */
+  }
+};----
+
+== 4. Register Mappings to Listeners
+
+To activate the mappings, you must register them to a Listener. Write your registration code after the code block where you have added the mappings to the inputManager.
+
+
+In the following example, you register the “Pause Game mapping to the `actionListener` object, because pausing a game is in “either/or decision.
+
+
+[source,java]
+----inputManager.addListener(actionListener, new String[]{"Pause Game"});----
+In the following example, you register navigational mappings to the `analogListener` object, because walking is a continuous action. Players typically keep the key pressed to express continuity, for example when they want to “walk on or “accelerate.
+
+
+[source,java]
+----inputManager.addListener(analogListener, new String[]{"Left", "Right"});----
+As you see, you can add several listeners in one String array. You can call the addListener() method more than once, each time with a subset of your list, if that helps you keep you code tidy. Again, the Listeners do not care about actual which keys are configured, you only register named trigger mappings.
+
+
+
+
+
+
+== 5. Implement Actions in Listeners
+
+You specify the action to be triggered where it says TODO in the Listener code snippets. Typically, you write a series of if/else conditions, testing for all the mapping names, and then calling the respective action. 
+
+
+Make use of the distinction between `if` and `else if` in this conditional.
+
+
+*  If several actions can be triggered simultaneously, test for all of these with a series of bare `if`s. For example, a character can be running forward _and_ to the left.
+*  If certain actions exclude one another, test for them with `else if`, the the rest of the exclusive tests can be skipped and you save some miliseconds. For example, you either shoot or pick something up.
+
+
+=== ActionListener
+
+In the most common case, you want an action to be triggered once, in the moment when the button or key trigger is released. For example, when the player presses a key to open a door, or clicks to pick up an item. For these cases, use an ActionListener and test for `&amp;&amp; !keyPressed`, like shown in the following example. 
+
+
+[source,java]
+----private ActionListener actionListener = new ActionListener() {
+    public void onAction(String name, boolean keyPressed, float tpf) {
+
+      if (name.equals("Pause Game") && !keyPressed) { // test?
+        isRunning = !isRunning;                       // action!
+      } 
+      
+      if ...
+
+    }
+  };
+----
+
+=== AnalogListener
+
+The following example shows how you define actions with an AnalogListener. These actions are triggered continuously, as long (intensity `value`) as the named key or mouse button is down. Use this listeners for semi-automatic weapons and navigational actions.
+
+
+[source,java]
+----private AnalogListener analogListener = new AnalogListener() {
+    public void onAnalog(String name, float value, float tpf) {
+
+      if (name.equals("Rotate")) {         // test?
+        player.rotate(0, value*speed, 0);  // action!
+      } 
+      
+      if ...
+
+    }
+  };----
+
+== Let Users Remap Keys
+
+It is likely that your players have different keyboard layouts, are used to “reversed mouse navigation, or prefer different navigational keys than the ones that you defined. You should create an options screen that lets users customize their mouse/key triggers for your mappings. Replace the trigger literals in the `inputManager.addMapping()` lines with variables, and load sets of triggers when the game starts. 
+
+
+The abstraction of separating triggers and mappings has the advantage that you can remap triggers easily. Your code only needs to remove and add some trigger mappings. The core of the code (the listeners and actions) remains unchanged. 
+
+<tags><tag target="keyinput" /><tag target="input" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,327 @@
+
+
+= Saving and Loading Materials with .j3m Files
+
+In the <<material_definitions#,Material Definitions>> article you learned how to configure <<materials_overview#,Materials>>  programmatically in Java code. If you have certain commonly used Materials that never change, you can clean up the amount of Java code that clutters your init method, by moving material settings into .j3m files. Then later in your code, you only need to call one setter instead of several to apply the material.
+
+
+If you want to colorize simple shapes (one texture all around), then .j3m are the most easily customizable solution. J3m files can contain texture mapped materials, but as usual you have to create the textures in an external editor, especially if you use UV-mapped textures. 
+
+
+
+== Writing the .j3m File
+
+.  For every Material, create a file and give it a name that describes it: e.g. `SimpleBump.j3m`
+.  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 {
+     MaterialParameters {
+         Shininess: 8.0
+         NormalMap: Textures/bump_rock_normal.png
+         UseMaterialColors : true
+         Ambient  : 0.0 0.0 0.0 1.0
+         Diffuse  : 1.0 1.0 1.0 1.0
+         Specular : 0.0 0.0 0.0 1.0
+     }
+}
+----
+
+How to this file is structured:
+
+
+.  Header
+..  `Material` is a fixed keyword, keep it.
+..  `shiny bumpy rock` is a descriptive string that you can make up. Choose a name to help you remember for what you intend to use this material.
+..  After the colon, specify on which <<materials_overview#,Material>> definition you base this Material.
+
+.  Now look up the choosen Material Definition's parameters and their parameter types from the <<materials_overview#,Material>> table. Add one line for each parameter.
+**  For example: The series of four numbers in the example above represent RGBA color values.
+
+.  Check the detailed syntax reference below if you are unsure.
+
+→→→
+
+
+
+== How to Use .j3m Materials
+
+This is how you use the prepared .j3m Material on a Spatial. Since you have saved the .j3m file to your project's Assets directory, the .j3m path is relative to `MyGame/src/assets/…`.
+
+
+[source,java]
+----myGeometry.setMaterial(assetManager.loadMaterial("Materials/SimpleBump.j3m"));----
+*Tip:* In the jMonkeyEngine SDK, open Windows&gt;Palette and drag the `JME Material: Set J3M` snippet into your code.
+
+
+
+== Syntax Reference for .j3m Files
+
+
+=== Paths
+
+Make sure to get the paths to the textures (.png, .jpg) and material definitions (.j3md) right. 
+
+
+*  The paths to the built-in .j3md files are relative to jME3's Core Data directory. Just copy the path stated in the <<materials_overview#,Material>> table. +
+`Common/MatDefs/Misc/Unshaded.j3md` is resolved to `jme3/src/src/core-data/Common/MatDefs/Misc/Unshaded.j3md`.
+*  The paths to your textures are relative to your project's assets directory. +
+`Textures/bump_rock_normal.png` is resolved to `MyGame/src/assets/Textures/bump_rock_normal.png`
+
+
+=== Data Types
+
+All data types (except Color) are specified in com.jme3.shader.VarType.
+“Color is specified as Vector4 in J3MLoader.java.
+
+[cols="3", options="header"]
+|===
+
+a|Name
+a|jME Java class
+a|.j3m file syntax
+
+a| Float
+a| (basic Java type) 
+a| a float (e.g. 0.72) , no comma or parentheses 
+
+a| Vector2
+a| `com.jme3.math.Vector2f`
+a| Two floats, no comma or parentheses 
+
+a| Vector3 
+a| `com.jme3.math.Vector3f` 
+a| Three floats, no comma or parentheses 
+
+a| Vector4
+a| `com.jme3.math.Vector4f` 
+a| Four floats, no comma or parentheses 
+
+a| Texture2D 
+a| `com.jme3.texture.Texture2D` 
+a| Path to texture in `assets` directory, no quotation marks 
+
+a| Texture3D
+a| `com.jme3.texture.Texture3D` 
+a| Same as texture 2D except it is interpreted as a 3D texture 
+
+a| TextureCubeMap
+a| `com.jme3.texture.TextureCubeMap` 
+a| Same as texture 2D except it is interpreted as a cubemap texture 
+
+a| Boolean
+a| (basic Java type) 
+a| `true` or `false` 
+
+a| Int
+a| (basic Java type) 
+a| Integer number, no comma or parentheses 
+
+a| Color 
+a| `com.jme3.math.ColorRGBA` 
+a| Four floats, no comma or parentheses 
+
+a| FloatArray
+a| 
+a| (Currently not supported in J3M) 
+
+a| Vector2Array
+a| 
+a| (Currently not supported in J3M) 
+
+a| Vector3Array
+a| 
+a| (Currently not supported in J3M) 
+
+a| Vector4Array
+a| 
+a| (Currently not supported in J3M) 
+
+a| Matrix3
+a| 
+a| (Currently not supported in J3M) 
+
+a| Matrix4
+a| 
+a| (Currently not supported in J3M) 
+
+a| Matrix3Array
+a| 
+a| (Currently not supported in J3M) 
+
+a| Matrix4Array
+a| 
+a| (Currently not supported in J3M) 
+
+a| TextureBuffer
+a| 
+a| (Currently not supported in J3M) 
+
+a| TextureArray
+a| 
+a| (Currently not supported in J3M) 
+
+|===
+
+
+=== Flip and Repeat Syntax
+
+*  A texture can be flipped using the following syntax `NormalMap: Flip Textures/bump_rock_normal.png`
+*  A texture can be set to repeat using the following syntax `NormalMap: Repeat Textures/bump_rock_normal.png`
+*  If a texture is set to both being flipped and repeated, Flip must come before Repeat
+
+
+=== Syntax for Additional Render States
+
+*  A Boolean can be “On or “Off
+*  Float is “123.0 etc
+*  Enum - values depend on the enum
+
+See the link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html[RenderState] javadoc for a detailed explanation of render states.
+
+[cols="3", options="header"]
+|===
+
+a|Name
+a|Type
+a|Purpose
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setWireframe(boolean)[Wireframe] 
+a|(Boolean)
+a| Enable wireframe rendering mode 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setFaceCullMode(com.jme3.material.RenderState.FaceCullMode)[FaceCull] 
+a|(Enum: FaceCullMode)
+a| Set face culling mode (Off, Front, Back, FrontAndBack) 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setDepthWrite(boolean)[DepthWrite] 
+a|(Boolean)
+a| Enable writing depth to the depth buffer 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setDepthTest(boolean)[DepthTest] 
+a|(Boolean)
+a| Enable depth testing 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setBlendMode(com.jme3.material.RenderState.BlendMode)[Blend] 
+a|(Enum: BlendMode)
+a| Set the blending mode 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setAlphaFallOff(float)[AlphaTestFalloff] 
+a|(Float)
+a| Set the alpha testing alpha falloff value (if set, it will enable alpha testing) 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setPolyOffset(float, float)[PolyOffset] 
+a|(Float, Float)
+a| Set the polygon offset factor and units 
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setColorWrite(boolean)[ColorWrite] 
+a|(Boolean)
+a| Enable color writing
+
+a| link:http://jmonkeyengine.org/javadoc/com/jme3/material/RenderState.html#setPointSprite(boolean)[PointSprite] 
+a|(Boolean)
+a| Enable point sprite rendering for point meshes 
+
+|===
+
+
+== Examples
+
+
+=== Example 1: Shiny
+
+[source,java]
+----
+Spatial signpost = (Spatial) assetManager.loadAsset(
+    new OgreMeshKey("Models/Sign Post/Sign Post.mesh.xml", null));
+signpost.setMaterial( assetManager.loadMaterial(
+    new AssetKey("Models/Sign Post/Sign Post.j3m")));
+TangentBinormalGenerator.generate(signpost);
+rootNode.attachChild(signpost);
+----
+The file `assets/Models/Sign Post/Sign Post.j3m` contains:
+
+
+[source]
+----
+Material Signpost : Common/MatDefs/Light/Lighting.j3md {
+    MaterialParameters {
+         Shininess: 4.0
+         DiffuseMap:  Models/Sign Post/Sign Post.jpg
+         NormalMap:   Models/Sign Post/Sign Post_normal.jpg
+         SpecularMap: Models/Sign Post/Sign Post_specular.jpg
+         UseMaterialColors : true
+         Ambient  : 0.5 0.5 0.5 1.0
+         Diffuse  : 1.0 1.0 1.0 1.0
+         Specular : 1.0 1.0 1.0 1.0
+    }
+}
+----
+The JPG files are in the same directory, `assets/Models/Sign Post/…`.
+
+
+
+=== Example 2: Repeating Texture
+
+[source,java]
+----
+Material mat = assetManager.loadMaterial(
+    "Textures/Terrain/Pond/Pond.j3m");
+mat.setColor("Ambient", ColorRGBA.DarkGray);
+mat.setColor("Diffuse", ColorRGBA.White);
+mat.setBoolean("UseMaterialColors", true);
+----
+The file `assets/Textures/Terrain/Pond/Pond.j3m` contains:
+
+
+[source]
+----
+Material Pong Rock : Common/MatDefs/Light/Lighting.j3md {
+     MaterialParameters {
+         Shininess: 8.0
+         DiffuseMap: Repeat Textures/Terrain/Pond/Pond.png
+         NormalMap:  Repeat Textures/Terrain/Pond/Pond_normal.png
+     }
+}
+----
+The PNG files are in the same directory, `assets/Textures/Terrain/Pond/`
+
+
+
+=== Example 3: Transparent
+
+The file `assets/Models/Tree/Leaves.j3m` contains:
+
+
+[source]
+----
+Material Leaves : Common/MatDefs/Light/Lighting.j3md {
+
+    Transparent On
+
+    MaterialParameters {
+        DiffuseMap : Models/Tree/Leaves.png
+        UseAlpha : true
+        AlphaDiscardThreshold : 0.5
+        UseMaterialColors : true
+        Ambient : .5 .5 .5 .5
+        Diffuse : 0.7 0.7 0.7 1
+        Specular : 0 0 0 1
+        Shininess : 16
+    }
+    AdditionalRenderState {
+        Blend Alpha
+        AlphaTestFalloff 0.50
+        FaceCull Off
+    }
+}
+----
+The PNG file is in the same directory, `assets/Models/Tree/…`
+
+
+
+== Related Links
+
+*  <<jme3/advanced/material_specification#,Developer specification of the jME3 material system (.j3md,.j3m)>>
+<tags><tag target="material" /><tag target="texture" /><tag target="file" /><tag target="sdk" /><tag target="wireframe" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,30 @@
+
+
+= Render Buckets
+
+For each viewport the rendering happens as follows:
+
+
+*  For each processor call preFrame
+*  Dispatch each geometry in a corresponding renderQueue (one for each Bucket) and build shadow queues
+*  For each processor call postQueues
+*  Rendering OpaqueBucket with object sorted front to back. (In order to minimize overdraw)
+*  Rendering SkyBucket with depth forced to 1.0. this means every object of this bucket will be far away and behind everything
+*  Rendering TransparentBucket with object sorted back to front. (So transparent objects can be seen correctly through each other)
+*  For each processor call postFrame
+*  Rendering TranslucentBucket with objects sorted back to front
+
+The translucent bucket is rendered at the end. That’s where you put transparent object that you don’t want to be affected by post processing ( shadows or what ever). Self-light-emitting particle emitters (such as a fire) are a good example.
+
+
+Post processors are not applied to this bucket with one exception : the FilterPostProcessor.
+
+
+The filter post processor hijacks the rendering process and renders a full screen quad with the texture of the scene applied on it.
+
+
+Once it’s done the depth buffer is 0, so it’s impossible to render a queue over it with proper depth test so if you use a FilterPostProcessor you have to add at the end of your filter stack the TranslucentBucketFilter. It will handle the translucent bucket rendering instead of the RenderManager. (Of course the correct depth information is passed to the filter).
+
+
+The nice side effect of this is that if you want to apply a post filter to your translucent bucket (like bloom for example) you can just push up the translucent bucket filter in the filter stack.
+

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

@@ -0,0 +1,542 @@
+
+
+= Shader Nodes
+
+
+=== Motivations
+
+jME3 material system is entirely based on shaders. While it's pretty powerful, this system has some issues and limitations : 
+
+
+*  Monolithic shaders have a serious lack of flexibility, and it can be daunting to get into the code for inexperienced users.
+*  Maintenance ease of such shaders is poor. (for example the whole lighting shaders represent around 500 lines of code, and it could be a lot worse with more features)
+*  Adding new features to those shaders decrease the ease of maintenance a lot. This point made us reluctant to do so and some feature were never added (Fog to name it, but many more).
+*  Users can't add their own feature to the shader unless they fork it, and fall back to the same issues explained in previous points.
+
+Shader Nodes were designed with this in mind and are the fruit of many long discussions in the core chat balancing the pros and cons of this or that pattern.+
+
+At first this system was referred to as “Shader injection. The basic idea was to allow users to inject code into shaders with a tag replacement system.+
+
+We finally came with a different concept called Shader Nodes, that is inspired from blender nodes system for textures and post process.+
+
+*The final shader is generated at run time by the system by assembling shader nodes together.*
+
+
+
+=== What is a Shader Node?
+
+Conceptually, it's just a self sufficient piece of glsl code that accepts inputs and produce some outputs.+
+
+Inputs are glsl variables that may be fed by previous nodes output values.+
+
+Outputs are glsl variables fed with values computed in the shader node code.+
+
+
+
+In practice it's a bit more than that.A shader node is declined in several parts :
+
+
+*  A shader node definition, defining : 
+**  The type of shader node (Vertex or Fragment for now)
+**  The minimal glsl version needed for the shader node
+**  The path to the shader file (containing the shader code heh)
+**  *A mandatory documentation block* for this Shader node. As I hope many users will do their own nodes and contribute them back this point is crucial.
+**  A list of inputs accepted by this shader (typed glsl variable optional or needed for the code to run properly)
+**  A list of outputs produced by this shader (typed glsl variable computed and fed by the node's code)
+
+*  The actual shader code file (.vert or .frag depending on the node's type like any shader file)
+*  A shader node declaration having :
+**  A unique name(in the shader scope)
+**  The shader node definition it's based on
+**  An optional activation condition (based on the actual define system)
+**  A list of input mapping (what will be actually fed to those inputs)
+**  A list of output mapping (what will be output to the global output of the shader)
+
+
+
+=== Shader Node definition
+
+First ShaderNodes have to be defined either in a separate file (j3sn for jme3 shader node) or directly embed in the Technique block of the j3md file.+
+
+Please refer to this documentation for global structure of a j3md file 
+<<jme3/advanced/material_specification#,jMonkeyEngine3 Material Specification>>
+
+
+All is included in a *ShaderNodeDefinitions* bloc. This block can have several nodes defined (it's recommended to define nodes that have strong dependencies with each other in the same j3sn file).+
+
+A ShaderNode is declared in a *ShaderNodeDefinition* block.+
+
+global structure should look like this :+
+
+
+
+[source,java]
+----
+ShaderNodeDefinitions{
+      ShaderNodeDefinition <NodeDefName>{
+            Type : <ShaderType> 
+            Shader <ShaderLangAndVersion> : <ShaderPath>
+            [Shader <ShaderLangAndVersion> : <ShaderPath>]
+            [...]
+            Documentation {
+                <DocContent>
+            } 
+            Input {
+                <GlslVarType> <VarName>
+                [<GlslVarType> <VarName>]
+                [...]
+            }
+            Output {
+                <GlslVarType> <VarName>
+                [<GlslVarType> <VarName>]
+                [...]
+            }
+      }
+      [ShaderNodeDefinition <NodeDef2Name> {
+         [...]
+      }]
+      [...]
+}
+----
+All that is not between [] is mandatory.+
+
+
+
+*  +++<u>ShaderNodeDefinition</u>+++ : the definition block. You can have several definition in the same ShaderNodeDefinitions block.
+**  *NodeDefName* : The name of this ShaderNodeDefinition
+
+*  +++<u>Type</u>+++ : define the type of this shader node
+**  *ShaderType* : The type of shader for this definition. For now only “Vertex and “Fragment are supported.
+
+*  +++<u>Shader</u>+++ : the version and path of the shader code to use. note that you can have several shader with different GLSL version. The generator will pick the relevant one according to GPU capabilities.
+**  *ShaderLangAndVersion* : follows the same syntax than the shader declaration in the j3md file : GLSL&lt;version&gt;, version being 100 for glsl 1.0 , 130 for glsl 1.3, 150 for glsl 1.5 and so on. Note that this is the *minimum* glsl version this shader supports
+**  *ShaderPath* the path to the shader code file (relative to the asset folder)
+
+*  +++<u>Documentation</u>+++ : the documentation block. This is mandatory and I really recommend filling this if you want to contribute your shader nodes. This documentation will be read buy the SDK and presented to users willing to add this node to their material definitions. This should contain a brief description of the node and a description for each input and ouput.
+**  *@input* can be use to prefix an input name so the sdk recognize it and format it accordingly. the syntax id @input &lt;inputName&gt; &lt;description&gt;.
+**  *@output* can be use to prefix an output name so the sdk recognize it and format it accordingly. the syntax id @output &lt;inputName&gt; &lt;description&gt;
+
+*  +++<u>Input</u>+++ : The input block containing all the inputs of this node. A node can have 1 or several inputs.
+**  *GlslVarType* : a valid glsl variable type that will be used in the shader for this input. see link:http://www.opengl.org/wiki/GLSL_Type[http://www.opengl.org/wiki/GLSL_Type] and the “Declare an array chapter
+**  *VarName* : the name of the variable. Note that you can't have several inputs with the same name.
+
+*  +++<u>Output</u>+++ : The output block containing all the outputs of this node. A node can have 1 or several outputs.
+**  *GlslVarType* : a valid glsl variable type that will be used in the shader for this input. see link:http://www.opengl.org/wiki/GLSL_Type[http://www.opengl.org/wiki/GLSL_Type] and the “Declare an array chapter
+**  *VarName* : the name of the variable. Note that you can't have several outputs with the same name.
+
+
+* Note that if you use the same name for an input and an ouput, the generator will consider them as the SAME variable so they should be of the same glsl type.*
+
+
+
+==== Example
+
+Here is a typical shader node definition
+
+
+[source,java]
+----
+ShaderNodeDefinitions{
+     ShaderNodeDefinition LightMapping{
+        Type: Fragment
+        Shader GLSL100: Common/MatDefs/ShaderNodes/LightMapping/lightMap.frag
+        Documentation {
+            This Node is responsible for multiplying a light mapping contribution to a given color.   
+            @input texCoord the texture coordinates to use for light mapping
+            @input lightMap the texture to use for light mapping   
+            @input color the color the lightmap color will be multiplied to
+            @output color the resulting color             
+        }
+        Input{            
+            vec2 texCoord
+            sampler2D lightMap    
+            vec4 color               
+        }
+        Output{
+            vec4 color
+        }
+    }   
+}    
+----
+
+==== Declare an array
+
+To declare an array you have to specify its size between square brackets.+
+
+*Constant size*+
+
+The size can be an int constant+
+
+_Example_
+
+
+[source]
+----
+      float myArray[10]
+----
+this will declare a float array with 10 elements.
+Any material parameter mapped with this array should be of FloatArray type and it's size will be assumed as 10 when the shader is generated.+
+
+
+
+*Material parameter driven size*+
+
+The size can be dynamic and driven by a material parameter. GLSL does not support non constant values for array declaration so this material parameter will be mapped to a define.+
+
+_Example_
+
+
+[source]
+----
+     float myArray[NumberOfElements]
+----
+This declares a float array with the size depending on the value of the NumberOfElement material parameter.+
+
+NumberOfElement *HAS* to be declared in the material definition as a material parameter. It will be mapped to a define and used in the shader.
+Not that if this value change the shader will have to be recompiled, due to the fact that it's mapped to a define.
+
+
+
+=== Shader Node code
+
+The shader code associated with a Shader node is similar to any shader code.+
+
+the code for a Vertex shader node should be in a .vert file and the code for a Fragment shader node should be in a .frag file.
+It has a declarative part containing variable declaration, function declaration and so on… And a main part that is embed in a “void main(){} block.+
+
+Input and output variables declared in the shader node definition can be used *without* being declared in the shader code. ( they shouldn't even or you'll have issues).+
+
+Here is a the code of the LightMap.frag shader.+
+
+
+
+[source,java]
+----
+void main(){
+    color *= texture2D(lightMap, texCoord);
+}
+----
+Very simple, it's just a texture fetch, but of course anything can be done.+
+
+*Do not declare uniforms, attributes or varyings in a shader node code*, the Generator will handle this, just use the inputs and outputs and optional local variables you may need.
+
+
+
+=== Shader Node declaration
+
+To create a shader we need to plug shader nodes to each other, but also interact with built in glsl inputs and outputs.
+Shader nodes are declared inside the Technique block. The vertex nodes are declared in the VertexShaderNodes block and the fragment nodes are declared in the FragmentShaderNodes block.+
+
+Note that if the j3md has ember shader nodes definition (in a ShaderNodesDefinitions block) it *must* be declared before the VertexShaderNodes and FragmentShaderNodes blocks.
+Of course there can be several ShaderNode declaration in those block.+
+
+Here is how a ShaderNode declaration should look :
+
+
+[source,java]
+----
+ShaderNode <ShaderNodeName>{
+     Definition : <DefinitionName> [: <DefinitionPath>]
+     [Condition : <ActivationCondition>]
+     InputMapping{
+          <InputVariableName>[.<Swizzle>] = <NameSpace>.<VarName>[.<Swizzle>] [: <MappingCondition>]
+          [...]
+     }
+     [OutputMapping{
+          <NameSpace>.<VarName>[.<Swizzle>] = <OutputVariableName>[.<Swizzle>] [: <MappingCondition>]
+          [...]
+     }]
+}
+----
+*  +++<u>ShaderNode</u>+++ the shader node block
+**  *ShaderNodeName* the name of this shader node, can be anything, but has to be *unique* in the shader scope
+
+*  +++<u>Definition</u>+++ : a reference to the shader node definition
+**  *DefinitionName* : the name of the definition this Node use. this definition can be declared in the same j3md or in its own j3sn file.
+**  *DefinitionPath* : in case the definition is declared in it's own j3sn file, you have to set the path to this file here.
+
+*  +++<u>Condition</u>+++ a condition that dictates if the node is active or not.
+**  *Activationcondition* : The condition for this node to be used. Today we use Defines to use different blocks of code used depending on the state of a Material Parameter. The condition here use the exact same paradigm. A valid condition must be the name of a material parameter or any combinations using logical operators “||,“&amp;&amp;,“! or grouping characters “( and “). The generator will create the corresponding define and the shader node code will be embed into and #ifdef statement.+
+
+
+
+    For example, let's say we have a Color and ColorMap material parameter, this condition “Color || ColorMap will generate this statement :
+
+
+[source,java]
+----
+        #if defined(COLOR) || defined(COLORMAP)
+            ...
+        #endif
+----
+*  +++<u>InputMapping</u>+++ the wiring of the inputs of this node, coming from previous node's outputs or from built in glsl inputs.
+**  *InputVariableName* : the name of the variable to map as declared in the definition.
+**  *Swizzle* : Swizling for the preceding variable. More information on glsl swizzling on this page link:http://www.opengl.org/wiki/GLSL_Type[http://www.opengl.org/wiki/GLSL_Type]
+**  *NameSpace* : The generator will use variable name space to avoid collision between variable names. Name space can be one of these values : 
+***  *MatParam* : the following variable is a Material Parameter declared in the MaterialParameters block of the materialDefinition
+***  *WorldParam* : the following variable is a World Parameter declared in the WorldParameters block of the current technique block. World parameters can be one of those declared in this file : link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/shader/UniformBinding.java[https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/shader/UniformBinding.java]
+***  *Attr* : the following variable is a shader attribute. It can be one those declared in the Type enum of the VertexBuffer class link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/VertexBuffer.java[https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/scene/VertexBuffer.java]
+***  *Global* : the variable is a global variable to the shader. Global variables will be assign at the end of the shader to glsl built in outputs : gl_Position for the vertex shader, or to one of the possible outputs of the fragment shader (for example  gl_FragColor). The global variable can have what ever name pleases you, it will assigned in the order they've been found in the declaration to the shader output. *Global variables can be inputs of a shader node. Global variables are forced to be vec4 and are defaulted to the value of the attribute inPosition in the vertex shader and vec4(1.0)(opaque white color) in the fragment shader*.
+***  *The name of a previous shader node* : this must be followed by and output variable of a the named shader node. This is what allows one to plug outputs from a node to inputs of another.
+
+**  *VarName* : the name of the variable to assign to the input. This variable must be known in name space declared before.
+**  *MappingCondition* : Follows the same rules as the activation condition for the shaderNode, this mapping will be embed in a #ifdef statement n the resulting shader.
+
+*  +++<u>OutputMapping</u>+++ : This block is optional, as mapping of output will be done in input mapping block of following shaderNodes, ecept if you want to output a value to the Global output of the shader.
+**  *NameSpace* : the name space of the output to assign, this can only be “Global here.
+**  *VarName* : the name of a global output (can be anything, just be aware that 2 different names result in 2 different outputs)
+**  *OutputVariable* : Must be an output of the current node's definition.
+**  *MappingCondition* : Same as before.
+
+
+
+=== Complete material definition and Shader Nodes example
+
+Here is an example of a very simple Material definition that just displays a solid color (controlled by a material parameter) on a mesh.
+
+
+
+[source,java]
+----
+MaterialDef Simple {
+    MaterialParameters {
+        Color Color
+    }
+    Technique {
+        WorldParameters {
+            WorldViewProjectionMatrix
+        }
+        VertexShaderNodes {
+            ShaderNode CommonVert {
+                Definition : CommonVert : Common/MatDefs/ShaderNodes/Common/CommonVert.j3sn
+                InputMappings {
+                    worldViewProjectionMatrix = WorldParam.WorldViewProjectionMatrix
+                    modelPosition = Global.position.xyz
+                }
+                OutputMappings {
+                    Global.position = projPosition
+                }
+            }
+        }
+        FragmentShaderNodes {
+            ShaderNode ColorMult {
+                Definition : ColorMult : Common/MatDefs/ShaderNodes/Basic/ColorMult.j3sn
+                InputMappings {
+                    color1 = MatParam.Color
+                    color2 = Global.color
+                }
+                OutputMappings {
+                    Global.color = outColor
+                }
+            }
+        }
+    }
+}
+----
+This Material definition has one Default technique with 2 node declarations.+
+
++++<u>*CommonVert Definition*</u>++++
+
+CommonVert is a vertex shader node that has commonly used input and outputs of a vertex shader. It also computes the position of the vertex in projection space
+here is the definition content (Common/MatDefs/ShaderNodes/Common/CommonVert.j3sn) : 
+
+
+[source,java]
+----
+ShaderNodesDefinitions {
+    ShaderNodeDefinition CommonVert {
+        Type: Vertex
+        Shader GLSL100: Common/MatDefs/ShaderNodes/Common/commonVert.vert
+        Documentation {
+            This Node is responsible for computing vertex position in projection space.
+            It also can pass texture coordinates 1 & 2, and vertexColor to the frgment shader as varying (or inputs for glsl >=1.3)                   
+            @input modelPosition the vertex position in model space (usually assigned with Attr.inPosition or Global.position)
+            @input worldViewProjectionMatrix the World View Projection Matrix transforms model space to projection space.
+            @input texCoord1 The first texture coordinates of the vertex (usually assigned with Attr.inTexCoord)
+            @input texCoord2 The second texture coordinates of the vertex (usually assigned with Attr.inTexCoord2)
+            @input vertColor The color of the vertex (usually assigned with Attr.inColor)                    
+            @output projPosition Position of the vertex in projection space.(usually assigned to Global.position)
+            @output vec2 texCoord1 The first texture coordinates of the vertex (output as a varying)
+            @output vec2 texCoord2 The second texture coordinates of the vertex (output as a varying)
+            @output vec4 vertColor The color of the vertex (output as a varying)
+        }                
+        Input{
+            vec3 modelPosition                    
+            mat4 worldViewProjectionMatrix                    
+            vec2 texCoord1
+            vec2 texCoord2
+            vec4 vertColor
+        }
+        Output{
+            vec4 projPosition
+            vec2 texCoord1
+            vec2 texCoord2
+            vec4 vertColor
+        }
+    }
+}
+----
+
+here is the shader Node code ( Common/MatDefs/ShaderNodes/Common/commonVert.vert)
+
+
+[source,java]
+----
+void main(){
+    projPosition = worldViewProjectionMatrix * vec4(modelPosition, 1.0);
+}
+----
+As you can see all the inputs and outputs are not used. that's because most of them are attributes meant to be passed to the fragment shader as varyings. all the wiring will be handled by the generator only if those variables are used in an input or output mapping.+
+
+
+
++++<u>*CommonVert input mapping*</u>++++
+
+here we have the most basic yet mandatory thing in a vertex shader, computing vertex position in projection space. for this we have 2 mapping :
+
+
+*  *worldViewProjectionMatrix = WorldParam.WorldViewProjectionMatrix* : the input parameter worldViewProjectionMatrix is assigned with the WorldViewProjectionMatrix World parameter declared in the WorlParameters block of the technique.
+*  *modelPosition = Global.position.xyz* : the modelPosition (understand the vertex position in the model coordinate space) is assigned with the Global position variable.
+
+
+
++++<u>*CommonVert output mapping*</u>++++
+
+
+
+*  *Global.position = projPosition* : The result of the multiplication of the worldViewProjectionMatrix  and the modelPosition is assigned to the Globale position
+
+
++++<u>*ColorMult Definition*</u>++++
+
+ColorMult is a very basic Shader Node that takes two colors as input and multiply them.
+here is the definition content (Common/MatDefs/ShaderNodes/Basic/ColorMult.j3sn) : 
+
+
+[source,java]
+----
+ShaderNodeDefinitions{
+    ShaderNodeDefinition ColorMult {      
+        Type: Fragment
+        Shader GLSL100: Common/MatDefs/ShaderNodes/Basic/colorMult.frag
+        Documentation{
+            Multiplies two colors
+            @input color1 the first color
+            @input color2 the second color            
+            @output outColor the resulting color
+        }
+        Input {
+            vec4 color1
+            vec4 color2            
+        }
+        Output {
+            vec4 outColor
+        }
+    }
+}
+----
+here is the shader Node code (Common/MatDefs/ShaderNodes/Basic/colorMult.frag)
+
+
+[source,java]
+----
+void main(){
+    outColor = color1 * color2;
+}
+----
++++<u>*ColorMult input mapping*</u>++++
+
+All inputs are mapped here :
+
+
+*  *color1 = MatParam.Color* : The first color is assigned to the Color Material parameter declared in the MaterialParameter block of the material definition  
+*  *color2 = Global.color* : The second color is assigned with the Global color variable. this is defaulted to vec4(1.0) (opaque white). Note that in a much complex material def this variable could already have been assigned with a previous Shader Node output
+
++++<u>*ColorMult output mapping*</u>++++
+
+
+
+*  *Global.color = outColor* : the resulting color is assigned to the Global color variable.
+
+
+
+
+
++++<u>*Generated shader code*</u>++++
+
+
+Vertex Shader (glsl 1.0)
+
+
+[source,java]
+----
+
+uniform mat4 g_WorldViewProjectionMatrix;
+
+attribute vec4 inPosition;
+
+void main(){
+        vec4 Global_position = inPosition;
+
+        //CommonVert : Begin
+        vec3 CommonVert_modelPosition = Global_position.xyz;
+        vec4 CommonVert_projPosition;
+        vec2 CommonVert_texCoord1;
+        vec2 CommonVert_texCoord2;
+        vec4 CommonVert_vertColor;
+
+        CommonVert_projPosition = g_WorldViewProjectionMatrix * vec4(CommonVert_modelPosition, 1.0);
+        Global_position = CommonVert_projPosition;
+        //CommonVert : End
+
+        gl_Position = Global_position;
+}
+----
+All materials parameter, world parameters, attributes varying are declared first. then for each shader node, the declarative part is appended.+
+
+For the main function, for each shader node, the input mappings are declared and assigned, the output are declared.+
+
+Then the variable names are replaced in the sahder node code with there complete name (NameSpace_varName), material parameters are replaced in the shader code as is.+
+
+Then, the output are mapped.+
+
+
+
+As you can see texCoord1/2 and vertColor are declared but never used. That's because the generator is not aware of that. By default it will declare all inputs in case they are used in the shaderNode code.
+Note that most glsl compiler will optimize this when compiling the shader on the GPU.
+
+
+Fragment Shader (glsl 1.0)
+
+
+[source,java]
+----
+
+uniform vec4 m_Color;
+
+void main(){
+        vec4 Global_color = vec4(1.0);
+
+        //ColorMult : Begin
+        vec4 ColorMult_color2 = Global_color;
+        vec4 ColorMult_outColor;
+
+        ColorMult_outColor = m_Color * ColorMult_color2;
+        Global_color = ColorMult_outColor;
+        //ColorMult : End
+
+        gl_FragColor = Global_color;
+}
+----
+Same as for the Vertex shader. note that the color1 is not declared, because it's directly replaced by the material parameter.
+
+
+
+
+
+For more explanations and design decisions please refer to the +++<abbr title="specification">spec</abbr>+++ here 
+link:https://docs.google.com/document/d/1S6xO3d1TBz0xcKe_MPTqY9V-QI59AKdg1OGy3U-HeVY/edit?usp=sharing[https://docs.google.com/document/d/1S6xO3d1TBz0xcKe_MPTqY9V-QI59AKdg1OGy3U-HeVY/edit?usp=sharing]
+
+
+Thank you for the brave ones that came through all this reading. i'm not gonna offer you a prize in exchange of a password, because we ran out of JME thongs…
+

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

@@ -0,0 +1,398 @@
+
+
+= JME3 and Shaders
+
++
+
+
+
+
+= Shaders Basics
+
+Shaders are sets of instructions that are executed on the GPU. They are used to take advantage of hardware acceleration available on the GPU for rendering purposes.+
+
+This paper only covers Vertex and Fragment shaders because they are the only ones supported by JME3 for the moment. But be aware that there are some other types of shaders (geometry, tessellation,…).+
+
+There are multiple frequently used languages that you may encounter to code shaders but as JME3 is based on OpenGL, shaders in JME use GLSL and any example in this paper will be written in GLSL.+
+
++
+
+
+
+
+=== How Does it work?
+
+To keep it Simple: The Vertex shader is executed once for each vertex in the view, then the Fragment shader (also called the Pixel shader) is executed once for each pixel on the screen.+
+
+The main purpose of the Vertex shader is to compute the screen coordinate of a vertex (where this vertex will be displayed on screen) while the main purpose of the Fragment shader is to compute the color of a pixel.+
+
+This is a very simplified graphic to describe the call stack: +
+
+image:jme3/advanced/jme3andshaders.png[jme3andshaders.png,with="",height=""]+
+
+The main program sends mesh data to the vertex shader (vertex position in object space, normals, tangents, etc..). The vertex shader computes the screen position of the vertex and sends it to the Fragment shader. The fragment shader computes the color, and the result is displayed on screen or in a texture.
++
+
+
+
+
+=== Variables scope
+
+There are different types of scope for variables in a shader :
+
+
+*  uniform : User defined variables that are passed by the main program to the vertex and fragment shader, these variables are global for a given execution of a shader.
+*  attribute : Per-vertex variables passed by the engine to the shader, like position, normal, etc (Mesh data in the graphic)
+*  varying : Variables passed from the vertex shader to the fragment shader.
+
+There is a large panel of variable types to be used, for more information about it I recommend reading the GLSL specification link:http://www.opengl.org/registry/doc/GLSLangSpec.Full.1.20.8.pdf[here].+
+
++
+
+
+
+
+=== Spaces and Matrices
+
+To understand the coming example you must know about the different spaces in 3D computer graphics, and the matrices used to translate coordinate from one space to another.+
+
+image:jme3/advanced/jme3andshaders-1.png[jme3andshaders-1.png,with="",height=""]+
+
+The engine passes the object space coordinates to the vertex shader. We need to compute its position in projection space. To do that we transform the object space position by the WorldViewProjectionMatrix which is a combination of the World, View, Projection matrices (who would have guessed?).+
+
++
+
+
+
+
+=== Simple example : rendering a solid color on an object
+
+Here is the simplest application to shaders, rendering a solid color.+
+
+Vertex Shader : +
+
+
+
+[source,java]
+----
+//the global uniform World view projection matrix
+//(more on global uniforms below)
+uniform mat4 g_WorldViewProjectionMatrix;
+//The attribute inPosition is the Object space position of the vertex
+attribute vec3 inPosition;
+void main(){
+    //Transformation of the object space coordinate to projection space
+    //coordinates.
+    //- gl_Position is the standard GLSL variable holding projection space
+    //position. It must be filled in the vertex shader
+    //- To convert position we multiply the worldViewProjectionMatrix by
+    //by the position vector.
+    //The multiplication must be done in this order.
+    gl_Position = g_WorldViewProjectionMatrix * vec4(inPosition, 1.0);
+}
+----
+Fragment Shader : +
+
+
+
+[source,java]
+----
+void main(){
+    //returning the color of the pixel (here solid blue)
+    //- gl_FragColor is the standard GLSL variable that holds the pixel
+    //color. It must be filled in the Fragment Shader.
+    gl_FragColor = vec4(0.0, 0.0, 1.0, 1.0);
+}
+----
+For example applying this shader to a sphere would render a solid blue sphere on screen.+
+
++
+
+
+
+
+= How to use shaders in JME3
+
+You probably heard that JME3 is “shader oriented”, but what does that mean?+
+
+Usually to use shaders you must create what is called a program. This program specify the vertex shader and the fragment shader to use.+
+
+JME3 encloses this in the material system. Every material in JME3 uses shaders.+
+
+For example let’s have a look at the SolidColor.j3md file : +
+
+
+
+[source,java]
+----
+MaterialDef Solid Color {
+    //This is the complete list of user defined uniforms to be used in the
+    //shaders
+    MaterialParameters {
+        Vector4 Color
+    }
+    Technique {
+        //This is where the vertex and fragment shader files are
+        //specified
+        VertexShader GLSL100:   Common/MatDefs/Misc/SolidColor.vert
+        FragmentShader GLSL100: Common/MatDefs/Misc/SolidColor.frag
+        //This is where you specify which global uniform you need for your
+        //shaders
+        WorldParameters {
+            WorldViewProjectionMatrix
+        }
+    }
+    Technique FixedFunc {
+    }
+}
+----
+For more information on JME3 material system, i suggest you read this link:http://jmonkeyengine.org/groups/development-discussion-jme3/forum/topic/jmonkeyengine3-material-system-full-explanation[topic].+
+
++
+
+
+
+
+=== JME3 Global uniforms
+
+JME3 can expose pre-computed global uniforms to your shaders. You must specify the one that are required for your shader in the WorldParameters section of the material definition file (.j3md).+
+
+Note that in the shader the uniform names will be prefixed by a “g_”.+
+
+In the example above, WorldViewProjectionMatrix is declared as uniform mat4 g_WorldViewProjectionMatrix in the shader.+
+
+The complete list of global uniforms that can be used in JME3 can be found link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/shader/UniformBinding.java[here].+
+
++
+
+
+
+
+=== JME3 Lighting Global uniforms
+
+JME3 uses some global uniforms for lighting :
+
+
+*  g_LightDirection (vec4) : the direction of the light
+**  use for SpotLight : x,y,z contain the world direction vector of the light, the w component contains the spotlight angle cosine 
+
+*  g_LightColor (vec4) : the color of the light
+*  g_LightPosition : the position of the light
+**  use for SpotLight : x,y,z contain the world position of the light, the w component contains 1/lightRange
+**  use for PointLight : x,y,z contain the world position of the light, the w component contains 1/lightRadius
+**  use for DirectionalLight : strangely enough it's used for the direction of the light…this might change though. The fourth component contains -1 and it's used in the lighting shader to know if it's a directionalLight or not.
+
+*  g_AmbientLightColor the color of the ambient light.
+
+These uniforms are passed to the shader without having to declare them in the j3md file, but you have to specify in the technique definition “ LightMode MultiPass see lighting.j3md for more information.
++
+
+
+
+
+=== JME3 attributes
+
+Those are different attributes that are always passed to your shader.+
+
+You can find a complete list of those attribute in the Type enum of the VertexBuffer link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/scene/VertexBuffer.java[here].+
+
+Note that in the shader the attributes names will be prefixed by an “in”.+
+
++
+
+When the enumeration lists some usual types for each attribute (for example texCoord specifies two floats) then that is the format expected by all standard JME3 shaders that use that attribute. When writing your own shaders though you can use alternative formats such as placing three floats in texCoord simply by declaring the attribute as vec3 in the shader and passing 3 as the component count into the mesh setBuffer call.
+
+
+
+=== User's uniforms
+
+At some point when making your own shader you'll need to pass your own uniforms+
+
+Any uniform has to be declared in the material definition file (.j3md) in the “MaterialParameters section.+
+
+
+
+[source,java]
+----
+    MaterialParameters {
+        Vector4 Color
+        Texture2D ColorMap
+    }
+----
+You can also pass some define to your vertex/fragment programs to know if an uniform as been declared. +
+
+You simply add it in the Defines section of your Technique in the definition file. +
+
+
+
+[source,java]
+----
+    Defines {
+        COLORMAP : ColorMap
+    }
+----
+For integer and floating point parameters, the define will contain the value that was set.+
+
+For all other types of parameters, the value 1 is defined.+
+
+If no value is set for that parameter, the define is not declared in the shader.+
+
+
+
+Those material parameters will be sent from the engine to the shader as follows, 
+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
+   material.setTexture("ColorMap", myTexture); // bind myTexture for that sampler uniform
+----
+To use this uniform in the shader, you need to declare it in the .frag or .vert files (depending on where you need it).
+You can make use of the defines here and later in the code:
+*Note that the “m_ prefix specifies that the uniform is a material parameter.*+
+
+
+
+[source,java]
+----
+   uniform vec4 m_Color;
+   #ifdef COLORMAP
+     uniform sampler2D m_ColorMap;
+   #endif
+----
+The uniforms will be populated at runtime with the value you sent.
+
+
+
+=== Example: Adding Color Keying to the Lighting.j3md Material Definition
+
+Color Keying is useful in games involving many players. It consists of adding some +
+
+player-specific color on models textures. +
+
+The easiest way of doing this is to use a keyMap which will contain the amount of +
+
+color to add in its alpha channel. +
+
+Here I will use this color map: link:http://wstaw.org/m/2011/10/24/plasma-desktopxB2787.jpg[http://wstaw.org/m/2011/10/24/plasma-desktopxB2787.jpg] +
+
+to blend color on this texture: link:http://wstaw.org/m/2011/10/24/plasma-desktopbq2787.jpg[http://wstaw.org/m/2011/10/24/plasma-desktopbq2787.jpg] +
+
++
+
+We need to pass 2 new parameters to the Lighting.j3md definition, MaterialParameters section :
+
+
+[source,java]
+----
+// Keying Map
+Texture2D KeyMap
+
+// Key Color 
+Color KeyColor
+----
+Below, add a new Define in the main Technique section:
+
+
+[source,java]
+----
+KEYMAP : KeyMap
+----
+In the Lighting.frag file, define the new uniforms:
+
+
+[source,java]
+----
+#ifdef KEYMAP
+  uniform sampler2D m_KeyMap;
+  uniform vec4 m_KeyColor;
+#endif
+----
+Further, when obtaining the diffuseColor from the DiffuseMap texture, check
+if we need to blend it:
+
+
+[source,java]
+----
+    #ifdef KEYMAP
+      vec4 keyColor = texture2D(m_KeyMap, newTexCoord);
+      diffuseColor.rgb = (1.0-keyColor.a) * diffuseColor.rgb + keyColor.a * m_KeyColor.rgb;
+    #endif
+----
+This way, a transparent pixel in the KeyMap texture doesn't modify the color. +
+
+A black pixel replaces it for the m_KeyColor and values in between are blended.+
+
++
+
+A result preview can be seen here: link:http://wstaw.org/m/2011/10/24/plasma-desktopuV2787.jpg[http://wstaw.org/m/2011/10/24/plasma-desktopuV2787.jpg]
+
+
+
+=== Step by step
+
+*  Create a vertex shader (.vert) file
+*  Create a fragment shader (.frag) file
+*  Create a material definition (j3md) file specifying the user defined uniforms, path to the shaders and the global uniforms to use
+*  In your initSimpleApplication, create a material using this definition, apply it to a geometry
+*  That’s it!!
+
+[source,java]
+----
+    // A cube
+    Box box= new Box(Vector3f.ZERO, 1f,1f,1f);
+    Geometry cube = new Geometry("box", box);
+    Material mat = new Material(assetManager,"Path/To/My/materialDef.j3md");
+    cube.setMaterial(mat);
+    rootNode.attachChild(cube);
+----
++
+
+
+
+
+=== JME3 and OpenGL 3 & 4 compatibility
+
+GLSL 1.0 to 1.2 comes with built in attributes and uniforms (ie, gl_Vertex, gl_ModelViewMatrix, etc…).+
+Those attributes are deprecated since GLSL 1.3 (opengl 3), hence JME3 global uniforms and attributes. Here is a list of deprecated attributes and their equivalent in JME3+
+
+
+[cols="2", options="header"]
+|===
+
+a|GLSL 1.2 attributes
+a|JME3 equivalent
+
+<a|gl_Vertex	
+a|inPosition
+
+<a|gl_Normal	
+a|inNormal
+
+<a|gl_Color	
+a|inColor
+
+<a|gl_MultiTexCoord0	
+a|inTexCoord
+
+<a|gl_ModelViewMatrix	
+a|g_WorldViewMatrix
+
+<a|gl_ProjectionMatrix	
+a|g_ProjectionMatrix
+
+<a|gl_ModelViewProjectionMatrix	
+a|g_WorldViewProjectionMatrix
+
+<a|gl_NormalMatrix	
+a|g_NormalMatrix
+
+|===
+
+
+=== Useful links
+
+link:http://www.eng.utah.edu/~cs5610/lectures/GLSL-ATI-Intro.pdf[http://www.eng.utah.edu/~cs5610/lectures/GLSL-ATI-Intro.pdf]
+

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

@@ -0,0 +1,216 @@
+
+
+= Gamma Correction or sRGB pipline
+
+
+== Overview
+
+Here is a quick overview of what lies under the “Gamma Correction term. +
+
+More in depth rundowns on the matter can be found here : link:http://http.developer.nvidia.com/GPUGems3/gpugems3_ch24.html[http://http.developer.nvidia.com/GPUGems3/gpugems3_ch24.html] and here link:http://www.arcsynthesis.org/gltut/Texturing/Tutorial%2016.html[http://www.arcsynthesis.org/gltut/Texturing/Tutorial%2016.html]
+
+
+We consider color values to be linear when computing lighting. What does that means? That means that we assume that the color 0.5,0.5,0.5 is half way between black and white.+
+
+The problem is that it’s not the case, or at least not when you look at the color through a monitor.+
+
+CRT monitors had physical limitations that prevented them to have a linear way of representing colors. that means that 0.5,0.5,0.5 through a monitor is not half way between black and white (it’s darker). Note that black and white remains the same though.+
+
++
+
+If we do not take that into account, the rendered images are overly darken and feels dull.+
+
++
+
+LCD monitors still mimic this physical limitation (I guess for backward compatibility).+
+
++
+
+*Output correct colors*+
+
+Gamma Correction is the technique that tends to correct the issue. Gamma is an power factor applied to the color by the monitor when lighting a pixel on screen (or at least a simplification of the function applied). So when we output the color, we have to apply the inverse power of this factor to nullify the effect : finalColor = pow(computedColor, 1/gamma);+
+
+
+
+*Knowing what colors we have as input*+
+
+The other aspect of gamma correction is the colors we get as input in the rendering process that are stored in textures or in ColorRGBA material params. Almost all image editors are storing color data in images already gamma corrected (so that colors are correct when you display the picture in a viewer of in a browser). Also most hand picked colors (in a color picker) can be assumed as gamma corrected as you most probably chose this color through a monitor display.
+Such images or color are said to be in sRGB color space, meaning “standard RGB” (which is not the standard one would guess).
+That means that textures and colors that we use as input in our shaders are not in a linear space. The issue is that we need them in linear space when we compute the lighting, else the lighting is wrong.
+To avoid this we need to apply some gamma correction to the colors : (pow(color, gamma);
+This only apply to textures that will render colors on screen (basically diffuse map, specular, light maps). Normal maps, height maps don’t need the correction.
+
+
+this is the kind of difference you can have :+
+
+left is non corrected output, right is gamma corrected output.+
+
+image:http///i.imgur.com/uNL7vw8.png[uNL7vw8.png,with="",height=""]
++
+
+
+
+
+=== Implementation
+
+*  To handle proper gamma corrected ouput colors, Opengl expose an ARB extension that allows you to output a color in linear space and have the GPU automatically correct it : link:https://www.opengl.org/registry/specs/ARB/framebuffer_sRGB.txt[https://www.opengl.org/registry/specs/ARB/framebuffer_sRGB.txt]
+
+*  To handle the input, instead of classic RGBA8 image format, one can use SRGB8_ALPHA8_EXT which is basically RGBA in sRGB. Using this you specify the GPU that the texture is in sRGB space and when fetching  a color from it, the GPU will linearize the color value for you (for free). There are sRGB equivalent to all 8 bits formats (even compressed format like DXT).+
+
+
+*  But all textures don't need this. For example, normal maps, height maps colors are most probably generated and not hand picked by an artist looking through a monitor. The implementation needs to account for it and expose a way to exclude some textures from the sRGB pipeline.
+
+Gamma Correction in jME 3.0 is based on those three statements.
+
+
+
+
+==== Turning Gamma Correction on/off
+
+You can turn Gamma Correction on and off using the AppSettings. There is a method setGammaCorrection(boolean) that changes the setting.
+use this in the main() method of your application : 
+
+
+[source,java]
+----
+AppSettings settings = new AppSettings(true);
+settings.setGammaCorrection(true);
+app.setSettings(settings);
+----
+This setting is also exposed in the Settings dialog displayed when you launch a jME application.+
+
+image:http///i.imgur.com/Lya1ldH.png[Lya1ldH.png,with="400",height=""]
+
+
+* But both can be enabled separately*
+
+
+
+
+===== Enabling output Gamma Correction
+
+You can enable or disable the Gamma correction of the rendered output by using 
+
+
+[source,java]
+----renderer.setMainFrameBufferSrgb(boolean srgb)----
+This will be ignored if the hardware doesn't have the GL_ARB_framebuffer_sRGB or the GL_EXT_texture_sRGB.
+This can be toggled at run time.
+
+
+This uses Opengl hardware gamma correction that uses an approximated Gamma value of 2.2 and uses the following formula : color = pow(color,1/gamma)+
+
+Not that this will not yield exact results, as the real gamma can vary depending on the monitor. +
+
+If this is a problem, please refer to the “handling gamma correction in a post process section.
+
+
+
+===== Enabling texture linearization
+
+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.
+
+
+
+All images marked as in sRGB color space will be uploaded to the GPU using a sRGB image format.
+Opengl hardware texture linearization also uses an approximated Gamma value of 2.2 and linearize the fetched texel color using the following formula : color = pow(color, gamma)+
+
+As with output gamma correction this will not give exact result, but the error is less important since most image editor uses the same approximation to correct images and save them in sRGB color space.
+
+
+Not all image format have their sRGB equivalent, and only 8bit formats.
+Here is an exhaustive list of the supported format and there equivalent :
+
+
+*  RGB8 : GL_SRGB8           
+*  RGBA8 : GL_SRGB8_ALPHA8
+*  BGR8 : GL_SRGB8  
+*  ABGR8 : GL_SRGB8_ALPHA8
+*  Luminance8 : GL_SLUMINANCE8
+*  Luminance8Alpha8 : GL_SLUMINANCE8_ALPHA8
+*  DXT1 : GL_COMPRESSED_SRGB_S3TC_DXT1
+*  DXT1A : GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT1
+*  DXT3 : GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT3
+*  DXT5 : GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5  
+
+
+
+
+
+==== Excluding images from the sRGB pipeline
+
++
+
+
+
+
+Not all images need to be linearized. Some images don't represent color information that will be displayed on screen, but more different sort of data packed in a texture.+
+
+The best example is a Normal map that will contains normal vectors for each pixel. Height maps will contain elevation values. These textures must not be linearized.
+
+
+There is no way to determine the real color space of an image when loading it, so we must deduce the color space from the usage it's loaded for.
+The usage is dictated by the material, those textures are used for, and by the material parameter they are assigned to.
+One can now specify in a material definition file (j3md) if a texture parameter must be assumed as in linear color space, and thus, must not be linearized, by using the keyword -LINEAR next to the parameter (case does not matter).
+
+
+For example here is how the NormalMap parameter is declared in the lighting material definition.
+
+
+[source]
+----
+ // Normal map
+ Texture2D NormalMap -LINEAR
+----
+When a texture is assigned to this material param by using material.setTexture(“NormalMap, myNormalTexture), the color space of this texture's image will be forced to linear. 
+So if you make your own material and want to use Gamma Correction, make sure you properly mark your textures as in the proper color space.
+
+
+This can sound complicated, but you just have to answer this question :  Does my image represent color data? if the answer is no, then you have to set the -Linear flag.
+
+
+
+==== ColorRGBA as sRGB
+
+*ALWAYS*
+
+
+
+If you want to set a color that you hand picked in a color picker, you should use the setAsSRGB method of ColorRGBA. This will convert the given values to linear color space by using the same formula as before : color = pow (color, gamma) where gamma = 2.2;
+
+
+If you want to retrieve those values from a ColorRGBA, you can call the getAsSRGB method. The values will be converted back to sRGB color Space.+
+
+Note that the return type of that method is a Vector4f and not a ColorRGBA, because as stated before, all ColorRGBA objects r,g,b attributes are assumed in Linear color space.
+
+
+
+==== Handling rendered output Gamma Correction with a post process filter
+
+As stated before, the hardware gamma correction uses and approximated gamma value of 2.2.
+Some may not be satisfied with that approximations and may want to pick a more appropriate gamma value.
+You can see in some games some Gamma calibration screens, that are here to help the player pick a correct gamma value for the monitor he's using.
+
+
+For this particular case, you can do as follow :
+
+
+.  Enable Gamma Correction global app setting.
+.  Disable rendered output correction : renderer.setMainFrameBufferSrgb(false); (for example in the simpleInit method of your SimpleApplication).
+.  Use the GammaCorrectionFilter in a FilterPostProcessor, and set the proper gamma value on it (default is 2.2).
+
+
+=== Should you use this?
+
+Yes. Mostly because it's the only way to have proper lighting.
+If you're starting a new project it's a no brainer…use it, period. And don't allow the player to turn it off.
+
+
+Now if you already spent time to adjust lighting in your scenes, without gamma correction, turning it on will make everything too bright, and you'll have to adjust all your lighting and colors again.
+That's why we kept a way to turn it off, for backward compatibility.
+

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

@@ -0,0 +1,165 @@
+
+
+= Level of Detail (LOD) Optimization
+
+A mesh with a high level of detail has lots of polygons and looks good close up. But when the mesh is further away (and the detail is not visible), the high-polygon count slows down performance unnecessarily. 
+
+
+One solution for this problem is to use high-detail meshes for objects close to the camera, and low-detail meshes for objects far from the camera. As the player moves through the scene, you must keep replacing close objects by more detailed meshes, and far objects by less detailed meshes. The goal is to keep few high-quality slow-rendering objects in the foreground, and many low-quality fast-rendering objects in the background. (Experienced users can compare this approach to <<jme3/advanced/terrain#,JME's TerraMonkey terrain system>>, which internally uses the specialized GeoMipMapping algorithm to generate a terrain's Levels of Detail.)
+
+
+You see now why you may want to be able to generate Levels of Detail for complex Geometries automatically. JME3 supports a Java implementation of the Ogre engine's LOD generator (originally by Péter Szücs and Stan Melax): You use link:https://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/tools/jme3tools/optimize/LodGenerator.java[jme3tools.optimize.LodGenerator] in conjunction with link:https://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/scene/control/LodControl.java[com.jme3.scene.control.LodControl]. 
+
+
+For a demo, run link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/stress/TestLodGeneration.java[TestLodGeneration.java] from <<sdk/sample_code#,JmeTests>>, then press +/- and spacebar to experiment. The following screenshots show a monkey model with three reduced Levels of Detail: 
+
+image::jme3/advanced/jmonkey-lod.gif[jmonkey-lod.gif,with="",height="",align="center"]
+
+
+
+
+== Usage
+
+To activate this optimization:
+
+
+.  Pick a reduction method and values for the Geometry. (Trial and error…)
+.  Generate LODs for the Geometry, either in the SDK or in code.
+.  Add an LOD control to the Geometry.
+
+
+== Pick Reduction Methods and Values
+
+There are several reduction methods to generate a low-polygon version from a high-polygon model. Don't worry, the reduction does not modify the original model.
+
+[cols="3", options="header"]
+|===
+
+a|Reduction Method
+a|Description
+a|Reduction Value
+
+a|LodGenerator.TriangleReductionMethod.COLLAPSE_COST
+a|Collapses polygon vertices from the mesh until the reduction cost (= amount of ugly artifacts caused) exceeds the given threshold.
+a|0.0f - 1.0f
+
+a|LodGenerator.TriangleReductionMethod.PROPORTIONAL
+a|Removes the given percentage of polygons from the mesh.
+a| 0.0f - 1.0f 
+
+a|LodGenerator.TriangleReductionMethod.CONSTANT
+a|Removes the given number of polygons from the mesh.
+a| integer 
+
+|===
+
+If you don't know which to choose, experiment. For example start by trying COLLAPSE_COST and .5f-.9f.
+
+
+
+== Generate LOD
+
+You must generate and cache several LODs for each mesh, ranging from many to few polygons. The LOD generator algorithm attempts to collaps vertices automatically, while avoiding ugly artifacts. The LOD generator doesn't generate new meshes, it only creates separate reduced index buffers for the more highly reduced levels.
+
+
+*  If you create geometries manually (3D models), use the SDK to generate LODs. 
+*  If you create geometries programmatically, generate LODs from your Java code.
+
+
+=== Generating LODs in the SDK
+
+The SDK contains a user-friendly interface to generate LODs for a model (.j3o file).
+
+
+.  Open the Projects or Files window.
+.  Select the .j3o file in the Project Assets &gt; Models directory.
+.  Choose Window&gt;SceneExplorer if the SceneExplorer is not open. Info about the selected model is now displayed in the SceneExplorer.
+.  Right-click the model in SceneExplorer. Choose the “Tools &gt; Generate Levels of Detail menu. +
+image:jme3/advanced/jme-sdk-generate-lod-menu.png[The &quot;Tools&gt;Generate LOD&quot; context menu in the SceneExplorer,with="300",height="180"]
+.  The “Generate LOD settings wizard opens: +
+ image:jme3/advanced/jme-sdk-generate-lod-window.png[The &quot;Generate LOD&quot; settings wizard,with="300",height="150"]
+.  Choose a reduction method and reduction values for one or more levels. +
+Tip: Enter higher reduction values for higher levels. 
+.  Click Finish to generate the LODs for this model.
+
+The LODs are saved in the .j3o model file.
+
+
+
+
+
+
+image::jme3/advanced/jme-sdk-generate-lod-full.png[jme-sdk-generate-lod-full.png,with="",height="",align="center"]
+
+
+
+
+=== Generating LODs in Code
+
+The `jme3tools.optimize.LodGenerator` utility class helps you generate LODs for an arbitrary mesh (a Geometry object) programmatically from your Java code. You create and bake one LodGenerator for each Geometry. 
+
+
+[source,java]
+----LodGenerator lod = new LodGenerator(geometry);
+lod.bakeLods(reductionMethod,reductionValue);----
+The LODs are stored inside the Geometry object. 
+
+
+*Example:* How to generate an LOD of myPrettyGeo's mesh with 50% fewer polygons:
+
+
+[source,java]
+----LodGenerator lod = new LodGenerator(myPrettyGeo);
+lod.bakeLods(LodGenerator.TriangleReductionMethod.PROPORTIONAL,0.5f);----
+
+== Activate the LOD Control
+
+After generating the LODs for the geometry, you create and add a `com.jme3.scene.control.LodControl` to the geometry. Adding the LodControl activates the LOD optimizaton for this geometry. 
+
+
+[source,java]
+----LodControl lc = new LodControl();
+myPrettyGeo.addControl(lc);
+rootNode.attachChild(myPrettyGeo);----
+The LodControl internally gets the camera from the game's viewport to calculate the distance to this geometry. Depending on the distance, the LodControl selects an appropriate level of detail, and passes more (or less) detailed vertex data to the renderer. 
+
+
+
+== Impact on Quality and Speed
+[cols="5", options="header"]
+|===
+
+a|Level number
+a|Purpose
+a|Distance
+a|Rendering Speed
+a|Rendering Quality
+
+a|“Level 0
+a|The original mesh is used automatically for close-ups, and it's the default if no LODs have been generated.
+a|Closest
+a|Slowest.
+a|Best.
+
+a|“Level 1 +
+“Level 2 +
+“Level 3 +
+…
+a|If you generated LODs, JME3 uses them automatically as soon as the object moves into the background.
+a|The higher the level, +
+the further away.
+a|The higher the level, +
+the faster.
+a|The higher the level, +
+the lower the quality.
+
+|===
+
+
+== See also
+
+*  link:http://hub.jmonkeyengine.org/forum/topic/brand-new-lod-generator/[http://hub.jmonkeyengine.org/forum/topic/brand-new-lod-generator/]
+*  link:https://github.com/worldforge/ember/tree/master/src/components/ogre/lod[https://github.com/worldforge/ember/tree/master/src/components/ogre/lod]
+*  link:http://www.melax.com/polychop[http://www.melax.com/polychop]
+*  link:http://sajty.elementfx.com/progressivemesh/GSoC2012.pdf[http://sajty.elementfx.com/progressivemesh/GSoC2012.pdf] 
+*  <<jme3/advanced/terrain#,JME3 TerraMonkey Terrain>>

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

@@ -0,0 +1,289 @@
+
+
+= Light and Shadow
+
+image:jme3/advanced/shading-ani.gif[Examples of shading and lighting.,with="",height=""]
+
+
+Light and Shadow are two separate things in 3D engines, although we percieve them together in real life:
+
+
+*  Lighting means that an object is brighter on the side facing the light direction, and darker on the backside. Computationally, this is relatively easy. 
+*  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.
+
+
+
+
+
+== Light Sources and Colors
+
+
+image::jme3/advanced/light-sources.png[A lit scene with multiple light sources,with="300",height="200",align="right"]
+
+
+
+You can add several types of light sources to a scene using `rootNode.addLight(mylight)`. 
+
+
+The available light sources in `com.​jme3.​light` are:
+
+
+*  SpotLight 
+*  PointLight
+*  AmbientLight
+*  DirectionalLight
+
+You control the color and intensity of each light source. Typically you set the color to white (`new ColorRGBA(1.0f,1.0f,1.0f,1.0f)` or `ColorRGBA.White`), which makes all scene elements appear in their natural color. 
+
+
+You can choose to use lights in other colors than white, or darker colors. This influences the scene's atmosphere and will make the scene appear colder (e.g. `ColorRGBA.Cyan`) or warmer (`ColorRGBA.Yellow`), brighter (higher values) or darker (lower values).
+
+
+You can get a list of all lights added to a Spatial by calling `getWorldLightList()` (includes inherited lights) or `getLocalLightList()` (only directly added lights), and iterating over the result.
+
+
+
+=== PointLight
+
+
+image::jme3/advanced/elephant-pointlights.png[An elephant model illuminated by pointlights,with="300",height="205",align="right"]
+
+
+
+A PointLight has a location and shines from there in all directions as far as its radius reaches. The light intensity decreases with increased distance from the light source. A PointLight can be used to cast shadows along with a PointLightShadowRenderer (see the Casting Shadows section)
+
+
+*Typical example:* Lamp, lightbulb, torch, candle.
+
+
+[source,java]
+----PointLight lamp_light = new PointLight();
+lamp_light.setColor(ColorRGBA.Yellow);
+lamp_light.setRadius(4f);
+lamp_light.setPosition(new Vector3f(lamp_geo.getLocalTranslation()));
+rootNode.addLight(lamp_light);----
+
+=== DirectionalLight
+
+
+image::jme3/advanced/house-directionallight.png[A house model illuminated with a sun-like directional light,with="300",height="210",align="right"]
+
+
+
+A DirectionalLight has no position, only a direction. It sends out parallel beams of light and is considered “infinitely far away. You typically have one directional light per scene. A DirectionalLight can be used together with shadows. 
+
+
+*Typically example:* Sun light.
+
+
+[source,java]
+----DirectionalLight sun = new DirectionalLight();
+sun.setColor(ColorRGBA.White);
+sun.setDirection(new Vector3f(-.5f,-.5f,-.5f).normalizeLocal());
+rootNode.addLight(sun);----
+
+=== SpotLight
+
+
+image::jme3/advanced/spotlight.png[Spotlight,with="",height="",align="right"]
+
+
+
+A SpotLight sends out a distinct beam or cone of light. A SpotLight has a direction, a position, distance (range) and two angles. The inner angle is the central maximum of the light cone, the outer angle the edge of the light cone. Everything outside the light cone's angles is not affected by the light.
+
+
+*Typical Example:* Flashlight
+
+
+[source,java]
+----SpotLight spot = new SpotLight();
+spot.setSpotRange(100f);                           // distance
+spot.setSpotInnerAngle(15f * FastMath.DEG_TO_RAD); // inner light cone (central beam)
+spot.setSpotOuterAngle(35f * FastMath.DEG_TO_RAD); // outer light cone (edge of the light)
+spot.setColor(ColorRGBA.White.mult(1.3f));         // light color
+spot.setPosition(cam.getLocation());               // shine from camera loc
+spot.setDirection(cam.getDirection());             // shine forward from camera loc
+rootNode.addLight(spot);----
+If you want the spotlight to follow the flycam, repeat the setDirection(…) and setPosition(…) calls in the update loop, and kee syncing them with the camera position and direction.
+
+
+
+=== AmbientLight
+
+An AmbientLight simply influences the brightness and color of the scene globally. It has no direction and no location and shines equally everywhere. An AmbientLight does not cast any shadows, and it lights all sides of Geometries evenly, which makes 3D objects look unnaturally flat; this is why you typically do not use an AmbientLight alone without one of the other lights.  
+
+
+*Typical example:* Regulate overall brightness, tinge the whole scene in a warm or cold color. 
+
+
+[source,java]
+----AmbientLight al = new AmbientLight();
+al.setColor(ColorRGBA.White.mult(1.3f));
+rootNode.addLight(al);----
++
+`mylight.setColor(ColorRGBA.White.mult(1.3f));`
+
+
+
+== Light Follows Spatial
+
+You can use a `com.jme3.scene.control.LightControl` to make a SpotLight or PointLight follow a Spatial. This can be used for a flashlight being carried by a character, or for car headlights, or an aircraft's spotlight, etc.
+
+
+[source,java]
+----
+PointLight myLight = new PointLight();
+rootNode.addLight(myLight);
+LightControl lightControl = new LightControl(myLight);
+spatial.addControl(lightControl); // this spatial controls the position of this light.
+----
+Obviously, this does not apply to AmbientLights, which have no position.
+
+
+
+== BasicShadowRenderer (deprecated)
+
+Full code sample
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestShadow.java[TestShadow.java]
+
+
+== Casting Shadows
+
+For each type of non-ambient light source, JME3 implements two ways to simulate geometries casting shadows on other geometries:
+
+
+*  a shadow renderer (which you apply to a viewport) and
+*  a shadow filter (which you can add to a viewport's filter post-processor).
+[cols="3", options="header"]
+|===
+
+a| light source class 
+a| shadow renderer class 
+a| shadow filter class 
+
+a| DirectionalLight 
+a| DirectionalLightShadowRenderer 
+a| DirectionalLightShadowFilter 
+
+a| PointLight 
+a| PointLightShadowRenderer 
+a| PointLightShadowFilter 
+
+a| SpotLight 
+a| SpotLightShadowRenderer 
+a| SpotLightShadowFilter 
+
+a| AmbientLight 
+a| (not applicable) 
+a| (not applicable) 
+
+|===
+
+You only need one shadow simulation per light source:  if you use shadow rendering, you won't need a shadow filter and vice versa.  Which way is more efficient depends partly on the complexity of your scene. All six shadow simulation classes have similar interfaces, so once you know how to use one, you can easily figure out the rest.
+
+
+Shadow calculations (cast and receive) have a performance impact, so use them sparingly.  With shadow renderers, you can turn off shadow casting and/or shadow receiving for individual geometries, for portions of the scene graph, or for the entire scene:
+
+
+[source,java]
+----
+spatial.setShadowMode(ShadowMode.Inherit);     // This is the default setting for new spatials.
+rootNode.setShadowMode(ShadowMode.Off);        // Disable shadows for the whole scene, except where overridden. 
+wall.setShadowMode(ShadowMode.CastAndReceive); // The wall can cast shadows and also receive them.
+floor.setShadowMode(ShadowMode.Receive);       // Any shadows cast by the floor would be hidden by it.
+airplane.setShadowMode(ShadowMode.Cast);       // There's nothing above the airplane to cast shadows on it.
+ghost.setShadowMode(ShadowMode.Off);           // The ghost is translucent: it neither casts nor receives shadows.
+----
+Both shadow renderers and shadow filters use shadow modes to determine which objects can cast shadows. However, only the shadow renderers pay attention to shadow modes when determining which objects receive shadows.  With a shadow filter, shadow modes have no effect on which objects receive shadows.
+
+
+Here's a sample application which demonstrates both DirectionalLightShadowRenderer and DirectionalLightShadowFilter:
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestDirectionalLightShadow.java[TestDirectionalLightShadow.java]
+
+Here is the key code fragment:
+
+
+[source,java]
+----
+        DirectionalLight sun = new DirectionalLight();
+        sun.setColor(ColorRGBA.White);
+        sun.setDirection(cam.getDirection());
+        rootNode.addLight(sun);
+
+        /* Drop shadows */
+        final int SHADOWMAP_SIZE=1024;
+        DirectionalLightShadowRenderer dlsr = new DirectionalLightShadowRenderer(assetManager, SHADOWMAP_SIZE, 3);
+        dlsr.setLight(sun);
+        viewPort.addProcessor(dlsr);
+
+        DirectionalLightShadowFilter dlsf = new DirectionalLightShadowFilter(assetManager, SHADOWMAP_SIZE, 3);
+        dlsf.setLight(sun);
+        dlsf.setEnabled(true);
+        FilterPostProcessor fpp = new FilterPostProcessor(assetManager);
+        fpp.addFilter(dlsf);
+        viewPort.addProcessor(fpp);
+----
+Constructor arguments:
+ * your AssetManager object
+ * size of the rendered shadow maps, in pixels per side (512, 1024, 2048, etc…)
+ * the number of shadow maps rendered (more shadow maps = better quality, but slower)
+
+
+Properties you can set:
+ * setDirection(Vector3f) – the direction of the light
+ * setLambda(0.65f) – to reduce the split size
+ * setShadowIntensity(0.7f) – shadow darkness (1=black, 0=invisible)
+ * setShadowZextend(float) – distance from camera to which shadows will be computed
+
+
+
+== Parallel-Split Shadow Map (deprecated)
+
+Full sample code
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/light/TestPssmShadow.java[TestPssmShadow.java]
+
+
+image::jme3/advanced/shadow.png[A lit scene with PSSM drop shadows,with="300",height="200",align="right"]
+
+
+
+[source,java]
+----private PssmShadowRenderer pssmRenderer;
+...
+public void simpleInitApp() {
+    ....
+    pssmRenderer = new PssmShadowRenderer(assetManager, 1024, 3);
+    pssmRenderer.setDirection(new Vector3f(-.5f,-.5f,-.5f).normalizeLocal()); // light direction
+    viewPort.addProcessor(pssmRenderer);
+----
+
+== Screen Space Ambient Occlusion
+
+Full sample code
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestSSAO.java[jme3/src/test/jme3test/post/TestSSAO.java] – Screen-Space Ambient Occlusion shadows
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/post/TestTransparentSSAO.java[jme3/src/test/jme3test/post/TestTransparentSSAO.java] – Screen-Space Ambient Occlusion shadows plus transparancy
+*  link:http://hub.jmonkeyengine.org/2010/08/screen-space-ambient-occlusion-for-jmonkeyengine-3-0/[Screen Space Ambient Occlusion for jMonkeyEngine (article)]
+
+Ambient Occlusion refers to the shadows which nearby objects cast on each other under an ambient lighting. Screen Space Ambient Occlusion (SSAO) approximates how light radiates in real life.
+
+
+In JME3, SSAO is implemented by adding an instance of `com.jme3.post.SSAOFilter` to a viewport which already simulates shadows using another method such as DirectionalLightShadowRenderer.
+
+
+[source,java]
+----
+FilterPostProcessor fpp = new FilterPostProcessor(assetManager);
+SSAOFilter ssaoFilter = new SSAOFilter(12.94f, 43.92f, 0.33f, 0.61f);
+fpp.addFilter(ssaoFilter);
+viewPort.addProcessor(fpp);
+----
+image:jme3/advanced/shading-textured-ani.gif[Shading with and without Ambient Occlusion,with="",height=""]
+

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

@@ -0,0 +1,545 @@
+
+
+=== Nifty Loading Screen (Progress Bar)
+
+There is a good tutorial about creating a nifty progress bar here:
+link:http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Create_your_own_Control_%28A_Nifty_Progressbar%29[http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Create_your_own_Control_%28A_Nifty_Progressbar%29]
+
+
+This example will use the existing hello terrain as an example.
+It will require these 2 images inside Assets/Interface/ (save them as border.png and inner.png respectively)
+
+
+image:jme3/advanced/inner1.png[inner1.png,with="",height=""]
+image:jme3/advanced/border1.png[border1.png,with="",height=""]
+
+
+This is the progress bar at 90%:
+
+
+image:jme3/advanced/loadingscreen.png[loadingscreen.png,with="",height=""]
+
+
+nifty_loading.xml
+
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<nifty>
+    <useStyles filename="nifty-default-styles.xml" />
+    <useControls filename="nifty-default-controls.xml" />
+  
+    <controlDefinition name = "loadingbar" controller = "jme3test.TestLoadingScreen">
+        <image filename="Interface/border.png" childLayout="absolute" 
+               imageMode="resize:15,2,15,15,15,2,15,2,15,2,15,15">
+            <image id="progressbar" x="0" y="0" filename="Interface/inner.png" width="32px" height="100%"
+                   imageMode="resize:15,2,15,15,15,2,15,2,15,2,15,15" />
+        </image>
+    </controlDefinition>
+    
+    <screen id="start" controller = "jme3test.TestLoadingScreen">
+        <layer id="layer" childLayout="center">
+            <panel id = "panel2" height="30%" width="50%" align="center" valign="center" childLayout="vertical"
+                   visibleToMouse="true">
+                <control id="startGame" name="button" backgroundColor="#0000" label="Load Game" align="center">
+                    <interact onClick="showLoadingMenu()" />
+                </control>
+            </panel>
+        </layer>
+    </screen>
+    
+    <screen id="loadlevel" controller = "jme3test.TestLoadingScreen">
+        <layer id="loadinglayer" childLayout="center" backgroundColor="#000000">
+            <panel id = "loadingpanel" childLayout="vertical" align="center" valign="center" height="32px" width="70%">
+                <control name="loadingbar" align="center" valign="center" width="100%" height="100%" />
+                <control id="loadingtext" name="label" align="center" 
+                         text="                                                  "/>
+            </panel>
+        </layer>
+    </screen>
+    
+    <screen id="end" controller = "jme3test.TestLoadingScreen">
+    </screen>
+    
+</nifty>
+----
+
+==== Understanding Nifty XML
+
+The progress bar and text is done statically using nifty XML.
+A custom control is created, which represents the progress bar.
+
+
+[source,xml]
+----
+    <controlDefinition name = "loadingbar" controller = "jme3test.TestLoadingScreen">
+        <image filename="Interface/border.png" childLayout="absolute" 
+               imageMode="resize:15,2,15,15,15,2,15,2,15,2,15,15">
+            <image id="progressbar" x="0" y="0" filename="Interface/inner.png" width="32px" height="100%"
+                   imageMode="resize:15,2,15,15,15,2,15,2,15,2,15,15"/>
+        </image>
+    </controlDefinition>
+----
+This screen simply displays a button in the middle of the screen, which could be seen as a simple main menu UI.
+
+
+[source,xml]
+----
+    <screen id="start" controller = "jme3test.TestLoadingScreen">
+        <layer id="layer" childLayout="center">
+            <panel id = "panel2" height="30%" width="50%" align="center" valign="center" childLayout="vertical"
+                   visibleToMouse="true">
+                <control id="startGame" name="button" backgroundColor="#0000" label="Load Game" align="center">
+                    <interact onClick="showLoadingMenu()" />
+                </control>
+            </panel>
+        </layer>
+    </screen>
+----
+This screen displays our custom progress bar control with a text control
+
+
+[source,xml]
+----
+    <screen id="loadlevel" controller = "jme3test.TestLoadingScreen">
+        <layer id="loadinglayer" childLayout="center" backgroundColor="#000000">
+            <panel id = "loadingpanel" childLayout="vertical" align="center" valign="center" height="32px" width="400px">
+                <control name="loadingbar" align="center" valign="center" width="400px" height="32px" />
+                <control id="loadingtext" name="label" align="center"
+                          text="                                                  "/>
+            </panel>
+        </layer>
+    </screen>
+----
+
+=== Creating the bindings to use the Nifty XML
+
+There are 3 main ways to update a progress bar. To understand why these methods are necessary, an understanding of the graphics pipeline is needed. 
+
+
+Something like this in a single thread will not work:
+
+
+[source,java]
+----
+load_scene();
+update_bar(30%);
+load_characters();
+update_bar(60%);
+load_sounds();
+update_bar(100%);
+----
+If you do all of this in a single frame, then it is sent to the graphics card only after the whole code block has executed. By this time the bar has reached 100% and the game has already begun – for the user, the progressbar on the screen would not have visibly changed.
+
+
+The 2 main good solutions are:
+
+
+.  Updating explicitly over many frames
+.  Multi-threading
+
+
+==== Updating progress bar over a number of frames
+
+The idea is to break down the loading of the game into discrete parts
+
+
+[source,java]
+----
+package jme3test;
+
+import com.jme3.niftygui.NiftyJmeDisplay;
+import de.lessvoid.nifty.Nifty;
+import de.lessvoid.nifty.elements.Element;
+import de.lessvoid.nifty.input.NiftyInputEvent;
+import de.lessvoid.nifty.screen.Screen;
+import de.lessvoid.nifty.screen.ScreenController;
+import de.lessvoid.nifty.tools.SizeValue;
+import com.jme3.app.SimpleApplication;
+import com.jme3.material.Material;
+import com.jme3.renderer.Camera;
+import com.jme3.terrain.geomipmap.TerrainLodControl;
+import com.jme3.terrain.heightmap.AbstractHeightMap;
+import com.jme3.terrain.geomipmap.TerrainQuad;
+import com.jme3.terrain.heightmap.ImageBasedHeightMap;
+import com.jme3.texture.Texture;
+import com.jme3.texture.Texture.WrapMode;
+import de.lessvoid.nifty.controls.Controller;
+import de.lessvoid.nifty.elements.render.TextRenderer;
+import de.lessvoid.xml.xpp3.Attributes;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Properties;
+import jme3tools.converters.ImageToAwt;
+
+public class TestLoadingScreen extends SimpleApplication implements ScreenController, Controller {
+
+    private NiftyJmeDisplay niftyDisplay;
+    private Nifty nifty;
+    private Element progressBarElement;
+    private TerrainQuad terrain;
+    private Material mat_terrain;
+    private float frameCount = 0;
+    private boolean load = false;
+    private TextRenderer textRenderer;
+
+    public static void main(String[] args) {
+        TestLoadingScreen app = new TestLoadingScreen();
+        app.start();
+    }
+
+    @Override
+    public void simpleInitApp() {
+        flyCam.setEnabled(false);
+        niftyDisplay = new NiftyJmeDisplay(assetManager,
+                inputManager,
+                audioRenderer,
+                guiViewPort);
+        nifty = niftyDisplay.getNifty();
+
+        nifty.fromXml("Interface/nifty_loading.xml", "start", this);
+
+        guiViewPort.addProcessor(niftyDisplay);
+    }
+
+    @Override
+    public void simpleUpdate(float tpf) {
+
+        if (load) { //loading is done over many frames
+            if (frameCount == 1) {
+                Element element = nifty.getScreen("loadlevel").findElementByName("loadingtext");
+                textRenderer = element.getRenderer(TextRenderer.class);
+                
+                mat_terrain = new Material(assetManager, "Common/MatDefs/Terrain/Terrain.j3md");
+                mat_terrain.setTexture("Alpha", assetManager.loadTexture("Textures/Terrain/splat/alphamap.png"));
+                setProgress(0.2f, "Loading grass");
+
+            } else if (frameCount == 2) {
+                Texture grass = assetManager.loadTexture("Textures/Terrain/splat/grass.jpg");
+                grass.setWrap(WrapMode.Repeat);
+                mat_terrain.setTexture("Tex1", grass);
+                mat_terrain.setFloat("Tex1Scale", 64f);
+                setProgress(0.4f, "Loading dirt");
+
+            } else if (frameCount == 3) {
+                Texture dirt = assetManager.loadTexture("Textures/Terrain/splat/dirt.jpg");
+
+                dirt.setWrap(WrapMode.Repeat);
+                mat_terrain.setTexture("Tex2", dirt);
+                mat_terrain.setFloat("Tex2Scale", 32f);
+                setProgress(0.5f, "Loading rocks");
+
+            } else if (frameCount == 4) {
+                Texture rock = assetManager.loadTexture("Textures/Terrain/splat/road.jpg");
+
+                rock.setWrap(WrapMode.Repeat);
+
+                mat_terrain.setTexture("Tex3", rock);
+                mat_terrain.setFloat("Tex3Scale", 128f);
+                setProgress(0.6f, "Creating terrain");
+
+            } else if (frameCount == 5) {
+                AbstractHeightMap heightmap = null;
+                Texture heightMapImage = assetManager.loadTexture("Textures/Terrain/splat/mountains512.png");
+                heightmap = new ImageBasedHeightMap(heightMapImage.getImage());
+
+                heightmap.load();
+                terrain = new TerrainQuad("my terrain", 65, 513, heightmap.getHeightMap());
+                setProgress(0.8f, "Positioning terrain");
+
+            } else if (frameCount == 6) {
+                terrain.setMaterial(mat_terrain);
+
+                terrain.setLocalTranslation(0, -100, 0);
+                terrain.setLocalScale(2f, 1f, 2f);
+                rootNode.attachChild(terrain);
+                setProgress(0.9f, "Loading cameras");
+
+            } else if (frameCount == 7) {
+                List<Camera> cameras = new ArrayList<Camera>();
+                cameras.add(getCamera());
+                TerrainLodControl control = new TerrainLodControl(terrain, cameras);
+                terrain.addControl(control);
+                setProgress(1f, "Loading complete");
+
+            } else if (frameCount == 8) {
+                nifty.gotoScreen("end");
+                nifty.exit();
+                guiViewPort.removeProcessor(niftyDisplay);
+                flyCam.setEnabled(true);
+                flyCam.setMoveSpeed(50);
+            }
+
+            frameCount++;
+        }
+    }
+
+    public void setProgress(final float progress, String loadingText) {
+        final int MIN_WIDTH = 32;
+        int pixelWidth = (int) (MIN_WIDTH + (progressBarElement.getParent().getWidth() - MIN_WIDTH) * progress);
+        progressBarElement.setConstraintWidth(new SizeValue(pixelWidth + "px"));
+        progressBarElement.getParent().layoutElements();
+        
+        textRenderer.setText(loadingText);
+    }
+
+    public void showLoadingMenu() {
+        nifty.gotoScreen("loadlevel");
+        load = true;
+    }
+
+    @Override
+    public void onStartScreen() {
+    }
+
+    @Override
+    public void onEndScreen() {
+    }
+
+    @Override
+    public void bind(Nifty nifty, Screen screen) {
+        progressBarElement = nifty.getScreen("loadlevel").findElementByName("progressbar");
+    }
+
+    // methods for Controller
+    @Override
+    public boolean inputEvent(final NiftyInputEvent inputEvent) {
+        return false;
+    }
+
+    @Override
+    public void bind(Nifty nifty, Screen screen, Element elmnt, Properties prprts, Attributes atrbts) {
+        progressBarElement = elmnt.findElementByName("progressbar");
+    }
+
+    @Override
+    public void init(Properties prprts, Attributes atrbts) {
+    }
+
+    public void onFocus(boolean getFocus) {
+    }
+}
+----
+Note:
+
+
+*  Try and add all controls near the end, as their update loops may begin executing
+
+
+==== Using multithreading
+
+For more info on multithreading: <<jme3/advanced/multithreading#,The jME3 Threading Model>>
+
+
+Make sure to change the XML file to point the controller to TestLoadingScreen*1*
+
+
+[source,java]
+----
+package jme3test;
+
+import com.jme3.niftygui.NiftyJmeDisplay;
+import de.lessvoid.nifty.Nifty;
+import de.lessvoid.nifty.elements.Element;
+import de.lessvoid.nifty.input.NiftyInputEvent;
+import de.lessvoid.nifty.screen.Screen;
+import de.lessvoid.nifty.screen.ScreenController;
+import de.lessvoid.nifty.tools.SizeValue;
+import com.jme3.app.SimpleApplication;
+import com.jme3.material.Material;
+import com.jme3.renderer.Camera;
+import com.jme3.terrain.geomipmap.TerrainLodControl;
+import com.jme3.terrain.heightmap.AbstractHeightMap;
+import com.jme3.terrain.geomipmap.TerrainQuad;
+import com.jme3.terrain.heightmap.ImageBasedHeightMap;
+import com.jme3.texture.Texture;
+import com.jme3.texture.Texture.WrapMode;
+import de.lessvoid.nifty.controls.Controller;
+import de.lessvoid.nifty.elements.render.TextRenderer;
+import de.lessvoid.xml.xpp3.Attributes;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Properties;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledThreadPoolExecutor;
+import jme3tools.converters.ImageToAwt;
+
+public class TestLoadingScreen1 extends SimpleApplication implements ScreenController, Controller {
+
+    private NiftyJmeDisplay niftyDisplay;
+    private Nifty nifty;
+    private Element progressBarElement;
+    private TerrainQuad terrain;
+    private Material mat_terrain;
+    private boolean load = false;
+    private ScheduledThreadPoolExecutor exec = new ScheduledThreadPoolExecutor(2);
+    private Future loadFuture = null;
+    private TextRenderer textRenderer;
+
+    public static void main(String[] args) {
+        TestLoadingScreen1 app = new TestLoadingScreen1();
+        app.start();
+    }
+
+    @Override
+    public void simpleInitApp() {
+        flyCam.setEnabled(false);
+        niftyDisplay = new NiftyJmeDisplay(assetManager,
+                inputManager,
+                audioRenderer,
+                guiViewPort);
+        nifty = niftyDisplay.getNifty();
+
+        nifty.fromXml("Interface/nifty_loading.xml", "start", this);
+
+        guiViewPort.addProcessor(niftyDisplay);
+    }
+
+    @Override
+    public void simpleUpdate(float tpf) {
+        if (load) {
+            if (loadFuture == null) {
+                //if we have not started loading yet, submit the Callable to the executor
+                loadFuture = exec.submit(loadingCallable);
+            }
+            //check if the execution on the other thread is done
+            if (loadFuture.isDone()) {
+                //these calls have to be done on the update loop thread, 
+                //especially attaching the terrain to the rootNode
+                //after it is attached, it's managed by the update loop thread 
+                // and may not be modified from any other thread anymore!
+                nifty.gotoScreen("end");
+                nifty.exit();
+                guiViewPort.removeProcessor(niftyDisplay);
+                flyCam.setEnabled(true);
+                flyCam.setMoveSpeed(50);
+                rootNode.attachChild(terrain);
+                load = false;
+            }
+        }
+    }
+    //this is the callable that contains the code that is run on the other thread.
+    //since the assetmananger is threadsafe, it can be used to load data from any thread
+    //we do *not* attach the objects to the rootNode here!
+    Callable<Void> loadingCallable = new Callable<Void>() {
+
+        public Void call() {
+
+            Element element = nifty.getScreen("loadlevel").findElementByName("loadingtext");
+            textRenderer = element.getRenderer(TextRenderer.class);
+
+            mat_terrain = new Material(assetManager, "Common/MatDefs/Terrain/Terrain.j3md");
+            mat_terrain.setTexture("Alpha", assetManager.loadTexture("Textures/Terrain/splat/alphamap.png"));
+            //setProgress is thread safe (see below)
+            setProgress(0.2f, "Loading grass");
+
+            Texture grass = assetManager.loadTexture("Textures/Terrain/splat/grass.jpg");
+            grass.setWrap(WrapMode.Repeat);
+            mat_terrain.setTexture("Tex1", grass);
+            mat_terrain.setFloat("Tex1Scale", 64f);
+            setProgress(0.4f, "Loading dirt");
+
+            Texture dirt = assetManager.loadTexture("Textures/Terrain/splat/dirt.jpg");
+
+            dirt.setWrap(WrapMode.Repeat);
+            mat_terrain.setTexture("Tex2", dirt);
+            mat_terrain.setFloat("Tex2Scale", 32f);
+            setProgress(0.5f, "Loading rocks");
+
+            Texture rock = assetManager.loadTexture("Textures/Terrain/splat/road.jpg");
+
+            rock.setWrap(WrapMode.Repeat);
+
+            mat_terrain.setTexture("Tex3", rock);
+            mat_terrain.setFloat("Tex3Scale", 128f);
+            setProgress(0.6f, "Creating terrain");
+
+            AbstractHeightMap heightmap = null;
+            Texture heightMapImage = assetManager.loadTexture("Textures/Terrain/splat/mountains512.png");
+            heightmap = new ImageBasedHeightMap(heightMapImage.getImage());
+
+            heightmap.load();
+            terrain = new TerrainQuad("my terrain", 65, 513, heightmap.getHeightMap());
+            setProgress(0.8f, "Positioning terrain");
+
+            terrain.setMaterial(mat_terrain);
+
+            terrain.setLocalTranslation(0, -100, 0);
+            terrain.setLocalScale(2f, 1f, 2f);
+            setProgress(0.9f, "Loading cameras");
+
+            List<Camera> cameras = new ArrayList<Camera>();
+            cameras.add(getCamera());
+            TerrainLodControl control = new TerrainLodControl(terrain, cameras);
+            terrain.addControl(control);
+            setProgress(1f, "Loading complete");
+            
+            return null;
+        }
+    };
+
+    public void setProgress(final float progress, final String loadingText) {
+        //since this method is called from another thread, we enqueue the changes to the progressbar to the update loop thread
+        enqueue(new Callable() {
+
+            public Object call() throws Exception {
+                final int MIN_WIDTH = 32;
+                int pixelWidth = (int) (MIN_WIDTH + (progressBarElement.getParent().getWidth() - MIN_WIDTH) * progress);
+                progressBarElement.setConstraintWidth(new SizeValue(pixelWidth + "px"));
+                progressBarElement.getParent().layoutElements();
+
+                textRenderer.setText(loadingText);
+                return null;
+            }
+        });
+
+    }
+
+    public void showLoadingMenu() {
+        nifty.gotoScreen("loadlevel");
+        load = true;
+    }
+
+    @Override
+    public void onStartScreen() {
+    }
+
+    @Override
+    public void onEndScreen() {
+    }
+
+    @Override
+    public void bind(Nifty nifty, Screen screen) {
+        progressBarElement = nifty.getScreen("loadlevel").findElementByName("progressbar");
+    }
+
+    // methods for Controller
+    @Override
+    public boolean inputEvent(final NiftyInputEvent inputEvent) {
+        return false;
+    }
+
+    @Override
+    public void bind(Nifty nifty, Screen screen, Element elmnt, Properties prprts, Attributes atrbts) {
+        progressBarElement = elmnt.findElementByName("progressbar");
+    }
+
+    @Override
+    public void init(Properties prprts, Attributes atrbts) {
+    }
+
+    public void onFocus(boolean getFocus) {
+    }
+    
+    
+    @Override
+    public void stop() {
+        super.stop();
+        //the pool executor needs to be shut down so the application properly exits.
+        exec.shutdown();
+    }
+}
+
+----

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

@@ -0,0 +1,119 @@
+
+
+= Localizing jME 3 Games
+
+
+== Scope
+
+Localizing an application can mean several things: 
+
+
+*  At minimum you translate all messages and dialogs in the user interface to your target languages.
+*  You should also translate the “read me, help, and other documentation.
+*  Also translating web content related to the application makes sure international users find out about your localized game.
+*  If you go the whole way of internationalization, you also “translate metaphors in icons or symbols used. +
+E.g. For localizations to right-to-left languages, you must also adjust the whole flow of the UI (order of menus and buttons).
+
+There are tools that assist you with localizing Java Swing GUIs. jME3 applications do not typically have a Swing +++<abbr title="Graphical User Interface">GUI</abbr>+++, so those tools are not of much help. Just stick to the normal Java rules about using Bundle Properties:
+
+
+
+== Preparing the Localization
+
+*Tip:* The jMonkeyEngine SDK supports opening and editing Bundle.properties files. Also note the Tools &gt; Localization menu.
+
+
+To prepare the application for localization, you have to first identify all hard-coded messages.
+
+
+.  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);----
+.  Create one file named `Bundle.properties` in each directory where there are Java file that contain messages.
+.  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: ----
+.  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);----
+
+The language used in the Bundle.properties files will be the default language for your game.
+
+
+
+== Translating the Messages
+
+Each additional language comes in a set of files that is marked with a (usually) two-letter suffix. Common locales are de for German, en for English, fr for French, ja for Japanese, pt for Portuguese, etc.
+
+
+To translate the messages to another language, for example, German:
+
+
+.  Make a copy of the `Bundle.properties` files.
+.  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: ----
+ *Important:* Do not modify any of the keys (text to the left of the equal sign)!
+
+
+.  To test the German localization, start the application from the command line with `-Duser.language=de`. Note the parameter `de`.
+
+*Tip:* In the jMonkeyEngine SDK, you set this VM Option in the Project properties under Run. Here you can also save individual run configuraions for each language you want to test.
+
+
+To get the full list of language suffixes use 
+
+
+[source,java]
+----System.out.println(Arrays.toString(Locale.getISOLanguages()));----
+
+== Which Strings Not to Translate
+
+*Important:* In the Bundle.properties file, do not include any strings that are asset paths, node or geometry names, input mappings, or material layers.
+
+
+*  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");----
+*  Keep mappings: 
+[source,java]
+----inputManager.addMapping("Shoot", trigger);
+inputManager.addListener(actionListener, "Shoot");----
+
+Only localize messages and UI text!
+
+
+
+== Common Localization Problems
+
+Typical problems include:
+
+
+*  Localized strings will be of vastly different lengths and will totally break your UI layout. ⇒ Test every localization.
+*  Strings with variable text or numbers don't work the same in different languages. ⇒ Either work in grammatical cases/numbers/gender for each language, or use link:http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms[gettext] or link:http://userguide.icu-project.org/formatparse/messages[ICU4J].
+*  The localizer only sees the strings, without any context. E.g. does “Search History mean “display the history of searches, or “search through the history? ⇒ Use clear key labels. Work closely with the localizers if they require extra info, and add that info as comments to the translation file.
+*  Broken international characters ⇒ Make sure the files are saved with the same character encoding as the font file(s) you're using. Nowadays, that usually means UTF-8 since font files tend to come for Unicode.
+*  Missing international characters ⇒ Make sure that there's a glyph for every needed character in your font, either by using more complete font files or by having the translation changed.
+
+
+== More Documentation
+
+link:http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/[http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/]
+
+
+link:http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Localisation[http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Localisation]
+

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

@@ -0,0 +1,78 @@
+
+
+= Logging and Monitoring
+
+
+== Logging Like a Newbie
+
+Many developers just use `System.out.println()` to print diagnostic strings to the terminal. The problem with that is that before the release, you have to go through all your code and make certain you removed all these `println()` calls. You do not want your customers to see them, and needlessly worry about ominous outdated debugging diagnostics. 
+
+
+
+== Logging Like a Pro
+
+Instead of `println()`, use the standard Java logger from `java.util.logging`. It has many advantages for professional game development:
+
+
+*  You tag each message with its *log level*: Severe error, informative warning, etc.
+*  You can *switch off or on printing of log messages* up to certain log level with just one line of code.
+**  During development, you would set the log level to `fine`, because you want all warnings printed.
+**  For the release, you set the log level to only report `severe` errors, and never print informative diagnostics.
+
+*  The logger message string is *localizable* and can use variables. Optimally, you localize all error messages.
+
+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());----
+.  Declare the info that you want to include in the message. The variables (here `a, b, c`) can be any printable Java object. +
+Example: `Vector3f a = cam.getLocation();` 
+.  Put the variables in a new `Object` array. Refer to the variables as `{0},{1},{2}` etc in the message string. Variables are numbered in the order you put them into the `Object` array. 
+.  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});----
+**  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});----
+
+
+“_a reason and a solution_
+
+
+More details about link:http://download.oracle.com/javase/6/docs/api/java/util/logging/Level.html[Java log levels] here.
+
+
+
+== Switching the Logger on and off
+
+In the release version you will deactivate the logging output to the terminal.
+
+
+To deactivate the default logger for a release, you set the log level to only report `severe` messages:
+
+
+[source,java]
+----Logger.getLogger(””).setLevel(Level.SEVERE);----
+During development or a beta test, you can tune down the default logger, and set the log level to only report `warning`s:
+
+
+[source,java]
+----Logger.getLogger(””).setLevel(Level.WARNING);----
+To activate full logging, e.g. for debugging and testing, use the `fine` level: 
+
+
+[source,java]
+----Logger.getLogger(””).setLevel(Level.FINE);----
+
+== Advanced Error Handling
+
+When an uncaught exception reaches certain parts of the jME3 system then the default response is to log the error and then exit the application. This is because an error happening every frame will rapidly fill logs with repeated failings and potentially mask or over-write the original cause of the problem or even the application may continue for a while and then suffer other errors caused by the first and make the root cause hard to determine.
+
+
+This behaviour can be partially modified by overriding the method handleError in SimpleApplication, for example to display a custom message to users, or to provide users with information on how to report a bug or even to change the way that the error is logged. 
+

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

@@ -0,0 +1,90 @@
+
+
+= MakeHuman Blender OgreXML toolchain for creating and importing animated human characters
+
+This guide describes how to use MakeHuman Blender OgreXML toolchain.
+
+
+
+=== Tools
+
+The latest versions at time of writing are:
+
+
+*  MakeHuman: 1.0.2
+*  Blender: 2.72
+*  OgreXML exporter for Blender: 0.6.0
+
+The tools can be downloaded from the following URLs:
+
+
+*  MakeHuman: [link:http://www.makehuman.org/][http://www.makehuman.org/]]
+*  Blender: [link:http://www.blender.org/][http://www.blender.org/]]
+*  OgreXML exporter for Blender: [link:https://code.google.com/p/blender2ogre/downloads/list][https://code.google.com/p/blender2ogre/downloads/list]]
+
+
+=== Seed Project
+
+Public domain seed project with some preset characters and animations:
+
+
+*  JME3 Open Asset Pack: [link:https://github.com/bubblecloud/jme3-open-asset-pack][https://github.com/bubblecloud/jme3-open-asset-pack]]
+
+
+=== Preparation
+
+.  Install MakeHuman and Blender.
+.  Install MakeHuman Blender importer from MakeHuman installation to Blender scripts folder and enable the script from Blender File → User Preferences → Addons.
+.  Install OgreXML exporter to Blender scripts folder and enable the script from Blender File → User Preferences → Addons.
+.  Clone the seed project or create your own project.
+.  Locate or create character model folder (src/main/resources/character/human/female)
+
+
+=== Creating Character Model with MakeHuman
+
+.  Create character model with MakeHuman. ([link:http://www.makehuman.org/documentation][http://www.makehuman.org/documentation]])
+**  NOTE: If you want to use JME3 Open Asset Pack animations without tweaking then use either male.mhm or female.mhm as preset and do not change the body proportions.
+
+.  Choose basic skeleton from Pose/Animate tab if you are not already using either of the presets.
+.  Export to blender exchange format from Files → Export tab.
+**  Choose Mesh Format → Blender exchange.
+**  Tick only Options → Feet on Ground and Scale Units → Meter 
+
+
+
+=== Animating Character Model with Blender
+
+.  Import the character model in blender exchange format (MHX) to Blender or open preset blender file female.blend.
+.  If you use your own character you can append animations from male.blend or female.blend preset files with Blender File → Append  function. Animations are in the animation folder.
+.  Tune the character model / materials and animate the character. ([link:http://www.blender.org/support/tutorials/][http://www.blender.org/support/tutorials/]])
+
+
+=== Exporting Character Model from Blender to Ogre XML
+
+.  Make sure that your scene objects in Blender do not have any spaces or special characters in their names. Rename them if they do.
+.  Arrange all your animations in single NLA track after each other without overlaps or touching in the timeline.
+.  Unlink any animations linked directly to your character armature or mesh.
+.  Export using Blender → File → Export Ogre3D (scene and mesh) and tick the following options:
+**  copy shader programs
+**  Export Scen
+**  Export Meshes
+**  Export Meshes (overwrite)
+**  Armature Animation
+**  Optimize Arrays
+**  Export Materials
+**  Tangents
+**  Reorganize Buffers
+**  Optimize Animations
+
+
+
+=== Importing Ogre XML to JME3
+
+You can load the ogre XML with asset manager or import them to SDK and hence convert them to JME3 asset format.
+
+
+You can test the animations by making your own version of AnimationPreviewer:
+
+
+link:https://github.com/bubblecloud/jme3-open-asset-pack/blob/master/src/main/java/com/jme3/asset/AnimationPreview.java[https://github.com/bubblecloud/jme3-open-asset-pack/blob/master/src/main/java/com/jme3/asset/AnimationPreview.java]
+

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

@@ -0,0 +1,149 @@
+
+
+= Making the Camera Follow a 3rd-Person Character
+
+When players steer a game character with 1st-person view, they directly steer the camera (`flyCam.setEnabled(true);`), and they never see the walking character itself. In a game with 3rd-person view, however, the players see the character walk, and you (the game developer) want to make the camera follow the character around when it walks.
+
+
+There are two ways how the camera can do that:
+
+
+*  Registering a chase camera to the player and the input manager.
+*  Attaching the camera to the character using a camera node.
+
+*Important:* Using third-person view requires you to deactivate the default flyCam (first-person view). This means that you have to configure your own navigation (<<jme3/advanced/input_handling#,key inputs and analogListener>>) that make your player character walk. For moving a physical player character, use `player.setWalkDirection()`, for a non-physical character you can use `player.move()`.
+
+
+
+== Code Samples
+
+Press the WASD or arrow keys to move. Drag with the left mouse button to rotate.
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestChaseCamera.java[TestChaseCamera.java]
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestCameraNode.java[TestCameraNode.java]
+
+
+== Camera Node
+
+To make the camera follow a target node, add this camera node code to your init method (e.g. `simpleInitApp()`). The `target` spatial is typically the player node.
+
+
+[source,java]
+----
+// Disable the default flyby cam
+flyCam.setEnabled(false);
+//create the camera Node
+camNode = new CameraNode("Camera Node", cam);
+//This mode means that camera copies the movements of the target:
+camNode.setControlDir(ControlDirection.SpatialToCamera);
+//Attach the camNode to the target:
+target.attachChild(camNode);
+//Move camNode, e.g. behind and above the target:
+camNode.setLocalTranslation(new Vector3f(0, 5, -5));
+//Rotate the camNode to look at the target:
+camNode.lookAt(target.getLocalTranslation(), Vector3f.UNIT_Y);
+----
+*Important:* Where the example says `camNode.setLocalTranslation(new Vector3f(0, 5, -5));`, you have to supply your own start position for the camera. This depends on the size of your target (the player character) and its position in your particular scene. Optimally, you set this to a spot a bit behind and above the target.
+
+[cols="2", options="header"]
+|===
+
+a|Methods
+a|Description
+
+a|setControlDir(ControlDirection.SpatialToCamera)
+a|User input steers the target spatial, and the camera follows the spatial.+
+The spatial's transformation is copied over the camera's transformation. +
+Example: Use with <<physics#,CharacterControl>>led spatial.
+
+a|setControlDir(ControlDirection.CameraToSpatial)
+a|User input steers the camera, and the target spatial follows the camera. +
+The camera's transformation is copied over the spatial's transformation. Use with first-person flyCam.
+
+|===
+
+*Code sample:*
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestCameraNode.java[TestCameraNode.java] – Press the WASD or arrow keys to move. Drag with the left mouse button to rotate.
+
+
+== Chase Camera
+
+To activate the chase camera, add the following code to your init method (e.g. `simpleInitApp()`). The `target` spatial is typically the player node. You will be able to rotate the target by dragging (keeping the left mouse button pressed and moving the mouse).
+
+
+[source,java]
+----
+// Disable the default flyby cam
+flyCam.setEnabled(false);
+// Enable a chase cam for this target (typically the player).
+ChaseCamera chaseCam = new ChaseCamera(cam, target, inputManager);
+chaseCam.setSmoothMotion(true);
+----[cols="2", options="header"]
+|===
+
+a|Method
+a|Description
+
+a|setInvertVerticalAxis(true)
+a|Invert the camera's vertical rotation Axis 
+
+a|setInvertHorizontalAxis(true)
+a|Invert the camera's horizontal rotation Axis
+
+a|setTrailingEnabled(true)
+a|Camera follows the target and flies around and behind when the target moves towards the camera. Trailing only works with smooth motion enabled. (Default)
+
+a|setTrailingEnabled(false)
+a|Camera follows the target, but does not rotate around the target when the target changes direction.
+
+a|setSmoothMotion(true)
+a|Activate SmoothMotion when trailing. This means the camera seems to accelerate and fly after the character, when it has caught up, it slows down again.
+
+a|setSmoothMotion(false)
+a|Disable smooth camera motion. Disabling SmoothMotion also disables trailing.
+
+a|setLookAtOffset(Vector3f.UNIT_Y.mult(3))
+a|Camera looks at a point 3 world units above the target.
+
+a|setToggleRotationTrigger(new MouseButtonTrigger(MouseInput.BUTTON_MIDDLE))
+a|Enable rotation by keeping the middle mouse button pressed (like in Blender). This disables the rotation on right and left mouse button click.
+
+a|setToggleRotationTrigger(new MouseButtonTrigger(+
+MouseInput.BUTTON_MIDDLE),+
+new KeyTrigger(KeyInput.KEY_SPACE))
+a|Activate mutiple triggers for the rotation of the camera, e.g. spacebar and middle mouse button, etc.
+
+a|setRotationSensitivity(5f)
+a|How fast the camera rotates. Use values around &lt;1.0f (all bigger values are ignored).
+
+|===
+
+*Code sample:*
+
+
+*  link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/input/TestChaseCamera.java[TestChaseCamera.java] – Press the WASD or arrow keys to move. Drag with the left mouse button to rotate.
+
+
+== Which to Choose?
+
+What is the difference of the two code samples above?
+
+[cols="2", options="header"]
+|===
+
+a|CameraNode
+a|ChaseCam
+
+a|Camera follows immediately, flies at same speed as target.
+a|Camera moves smoothly and accelerates and decelerates, flies more slowly than the target and catches up.
+
+a|Camera stays attached to the target at a constant distance.
+a|Camera orbits the target and approaches slowly.
+
+a|Drag-to-Rotate rotates the target and the camera. You always see the target from behind.
+a|Drag-to-Rotate rotates only the camera. You can see the target from various sides.
+
+|===

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

@@ -0,0 +1,129 @@
+
+
+= How to Use Material Definitions (.j3md)
+
+All Geometries need a Material to be visible. Every Material is based on a Material Definition. Material definitions provide the “logic for the material, and a shader draws the material according to the parameters specified in the definition. The J3MD file abstracts the shader and its configuration away from the user, allowing a simple interface where the user can simply set a few parameters on the material to change its appearance and the way its handled by the shaders. 
+
+
+The most common Material Definitions are included in the engine, advanced users can create custom ones. In this case you will also be interested in the <<jme3/advanced/material_specification#,in-depth developer specification of the jME3 material system>>.
+
+
+*Example:*
+
+
+[source,java]
+----Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
+Material mat = new Material(assetManager,  // Create new material and...
+    "Common/MatDefs/Misc/Unshaded.j3md");  // ... specify a Material Definition file, here "Unshaded.j3md"!
+mat.setColor("Color", ColorRGBA.Blue);     // Set one or more material parameters.
+myGeometry.setMaterial(mat);               // Use material on this Geometry.
+----
+<<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>>
+
+
+
+== Preparing a Material
+
+In the <<materials_overview#,Materials Overview>> list:
+
+
+.  Choose a Material Definition that has the features that you need. 
+**  Tip: If you don't know, start with `Unshaded.j3md` or `Lighting.j3md`.
+
+.  Look at the applicable parameters of the Material Definition and determine which parameters you need to achieve the desired effect (e.g. “glow or “color). Most parameters are optional! 
+.  Create and save the necessary Texture files to your `assets/Textures` directory.
+**  E.g. mytex_diffuse.png as ColorMap / DiffuseMap, mytex_normal.png as NormalMap, mytex_alpha.png as AlphaMap, etc…
+
+.  Determine the required values to achieve the effect that you want.
+**  E.g. set colors, floats, booleans, etc… 
+
+
+
+== Using a Material
+
+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 <<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));----
+
+For details see also: <<jme3/intermediate/how_to_use_materials#,How to Use Materials>>
+
+
+
+=== Examples
+
+Here are examples of the methods that set the different data types:
+
+
+*  `mat.setColor(   “Color,       ColorRGBA.White );` 
+*  `mat.setTexture( “ColorMap,    assetManager.loadTexture(“Interface/Logo/Monkey.png ));`
+*  `mat.setFloat(   “Shininess,   5f);`
+*  `mat.setBoolean( “SphereMap,   true);`
+*  `mat.setVector3( “NormalScale, new Vector3f(1f,1f,1f));`
+
+A simpled textured material.
+
+
+[source,java]
+----
+Material mat = new Material(assetManager, 
+    "Common/MatDefs/Misc/Unshaded.j3md");
+mat.setTexture("ColorMap", assetManager.loadTexture(
+    "Interface/Logo/Monkey.jpg"));
+----
+A textured material with a color bleeding through transparent areas.
+
+
+[source,java]
+----
+Material mat = new Material(assetManager, 
+    "Common/MatDefs/Misc/Unshaded.j3md");
+mat.setTexture("ColorMap", assetManager.loadTexture(
+    "Textures/ColoredTex/Monkey.png"));
+mat.setColor("Color", ColorRGBA.Blue);
+----
+You can test these examples within the following code snippet. It creates a box and applies the material:
+
+
+[source,java]
+---- Box b = new Box(Vector3f.ZERO, 1, 1, 1);
+Geometry geom = new Geometry("Box", b);
+// ... insert Material definition...
+geom.setMaterial(mat);
+rootNode.attachChild(geom);
+----
+
+
+
+
+== Creating a Custom Material Definition
+
+First read the <<jme3/advanced/material_specification#,developer specification of the jME3 material system (.j3md,.j3m)>>. Also check out the <<jme3/build_from_sources#,engine source code>> and have a look at how some Material Definitions are implemented. 
+
+
+You can create your own Material Definitions and place them in your project's `assets/MatDefs` directory.
+
+
+.  Find the existing MatDefs in `engine/src/core-data/Common/MatDefs/`. 
+.  Open a Something.j3md file in a text editor. You see that this .j3md file defines Material Parameters and Techniques.
+**  Material Parameters are the ones that you set in Materials, as shown in the examples above.
+**  The Techniques rely on VertexShaders and FragmentShaders: You find those in the files Something.vert and Something.frag in the same directory.
+
+.  Learn about GLSL (OpenGL Shading Language) to understand the .vert and .frag syntax, then write your own.
+
+
+== Related Links
+
+*  <<jme3/advanced/material_specification#,Developer specification of the jME3 material system (.j3md,.j3m)>>
+<tags><tag target="Material" /><tag target="SDK" /><tag target="MatDef" /><tag target="file" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,301 @@
+
+
+= jMonkeyEngine3 Material Specification
+
+
+== General Syntax
+
+Material definitions and material instance files are formatted similarly to curly-bracket languages, in other words, you have “blocks and other “blocks nested in them, surrounded by curly-brackets. There are statements inside the blocks, the next statement begins after a new line, or a semi-colon to allow two statements on the same line. Comments are made by prefixing with two slashes, the `/* */` style comments are not allowed.
+
+
+*Example:*
+
+
+[source]
+----RootBlock {
+  // Comment
+  SubBlock NameForTheBlock {
+    Statement1 // Another comment
+  }
+  SubBlock2 {
+    SubSubBlock {
+      Statement2
+      Statement3
+      // two statements on the same line
+      Statement4; Statement5
+    }
+  }
+  SubBlock3
+    { // bracket can be on next line as well
+    }
+}----
+The syntax for J3MD and J3M files follows from this base format.
+
+
+
+== Material Definition files (J3MD)
+
+Material definitions provide the “logic for the material. Usually a shader that will handle drawing the object, and corresponding parameters that allow configuration of the shader. The J3MD file abstracts the shader and its configuration away from the user, allowing a simple interface where one can simply set a few parameters on the material to change its appearance and the way it's handled.
+
+
+Material definitions support multiple techniques, each technique describes a different way to draw the object. For example, currently in jME3, an additional technique is used to render shadow maps for example.
+
+
+
+=== Shaders
+
+Shader support inside J3MD files is rather sophisticated. First, shaders may reference shader libraries, in a similar way to Java's “import statement, or C++'s “include pre-processor directive. Shader libraries in turn, can also reference other shader libraries this way. In the end, it is possible for a shader to use many functions together from many libraries and combine them in ways to create a more advanced effect. For example, any shader that wishes to take advantage of hardware skinning, can just import the skinning shader library and use the function, without having to write the specific logic needed for hardware skinning.
+
+
+Shaders can also take advantage of “defines that are specified inside material definitions.
+The defines “bind into material parameters, so that a change in a material parameter can apply or remove a define from the corresponding shader. This allows the shader to completely change in behavior during run-time.
+
+
+Although it is possible to use shader uniforms for the very same purpose, those may introduce slowdowns in older GPUs, that do not support branching. In that case, using defines can allow changing the way the shader works without using shader uniforms. In order to introduce a define into a shader, however, its source code must be changed, and therefore, it must be re-compiled. It is therefore not recommended to change define bound parameters often.
+
+
+
+=== Syntax of a J3MD file
+
+All J3MD files begin with `MaterialDef` as the root block, following that, is the name of the material def (in this example `Test Material 123`). The name is not used for anything important currently, except for debugging. The name is typed as is without quotes, and can have spaces.
+
+
+*Example of a first line of a J3MD file:*
+
+
+[source]
+----MaterialDef Test Material 123 {----
+Inside a MaterialDef block, there can be at most one MaterialParameters block, and one or more `Technique` blocks.
+
+
+Techniques may have an optional name, which specifies the name of the technique. If no name is specified for a technique, then its name is “Default, and it is used by default if the user does not specify another technique to use for the material.
+
+
+*Example of J3MD:*
+
+
+[source]
+----MaterialDef Test Material 123 { 
+  MaterialParameters { }
+  Technique { }
+  Technique NamedTech { } 
+}----
+Inside the MaterialParameters block, the parameters are specified. Every parameter has a type and a name. Material parameters are similar to Java variables in that aspect.
+
+
+*Example of a MaterialParameters block:*
+
+
+[source]
+----MaterialParameters {
+    Texture2D TexParam
+    Color     ColorParam
+    Vector3   VectorParam
+    Boolean   BoolParam
+// ...
+}----
+Whereas in the J3MD file, the parameter names and types are specified, in a J3M (Material instance) file, the values for these parameters are assigned, as will be shown later. This is how the materials are configured.
+
+
+At the time of writing, the following types of parameters are allowed inside J3MD files: Int, Boolean, Float, Vector2, Vector3, Vector4, Texture2D, TextureCubeMap.
+
+
+You can specify a default value for material parameters, inside material definitions, in the case that no value is specified in the material instance. 
+
+
+[source]
+----MaterialParameters {
+     Float MyParam : 1
+// ...
+}----
+1 will be used as the default value and sent to the shader if it has not been set by a meterial.setFloat() call.
+
+
+
+=== Techniques
+
+Techniques are more advanced blocks than the MaterialParameters block. Techniques may have nested blocks, any many types of statements.
+
+
+In this section, the statements and nested blocks that are allowed inside the Technique block will be described.
+
+
+The two most important statements, are the `FragmentShader` and `VertexShader` statements. These statements specify the shader to use for the technique, and are required inside the “Default technique. Both operate in the same way, after the statement, the language of the shader is specified, usually with a version number as well, for example `GLSL100` for OpenGL Shading Language version 1.00. Followed by a colon and an absolute path for an asset describing the actual shader source code. For GLSL, it is permitted to specify .glsl, .frag, and .vert files.
+
+
+When the material is applied to an object, the shader has its uniforms set based on the material parameter values specified in the material instance. but the parameter is prefixed with an“m_.
+
+
+For example, assuming the parameter `Shininess` is defined in the MaterialParameters block like so:
+
+
+[source]
+----MaterialParameters {
+  Float Shininess
+}----
+The value of that parameter will map into an uniform with same name with the “m_ prefix in the GLSL shader:
+
+
+[source]
+----uniform float m_Shininess;----
+The letter `m` in the prefix stands for material.
+
+
+
+=== World/Global parameters
+
+An important structure, that also relates to shaders, is the WorldParameters structure. It is similar in purpose to the MaterialParameters structure; it exposes various parameters to the shader, but it works differently. Whereas the user specified material parameters, world parameters are specified by the engine. In addition, the WorldParameters structure is nested in the Technique, because it is specific to the shader being used. For example, the Time world parameter specifies the time in seconds since the engine started running, the material can expose this parameter to the shader by specifying it in the WorldParameters structure like so:
+
+
+[source]
+----WorldParameters {
+  Time
+// ...
+}----
+The shader will be able to access this parameter through a uniform, also named `Time` but prefixed with `g_`:
+
+
+[source]
+----uniform float g_Time;----
+The `g` letter stands for “global, which is considered a synonym with “world in the context of parameter scope.
+
+
+There are many world parameters available for shaders, a comprehensive list will be specified elsewhere.
+
+
+
+=== RenderState
+
+The RenderState block specifies values for various render states in the rendering context. The RenderState block is nested inside the Technique block. There are many types of render states, and a comprehensive list will not be included in this document.
+
+
+The most commonly used render state is alpha blending, to specify it for a particular technique, including a RenderState block with the statement `Blend Alpha`.
+
+
+*Example:*
+
+
+[source]
+----RenderState {
+ Blend Alpha
+}----
+*Full Example of a J3MD*
+
+
+Included is a full example of a J3MD file using all the features learned:
+
+
+[source]
+----MaterialDef Test Material 123 { 
+  MaterialParameters {
+    Float m_Shininess
+    Texture2D m_MyTex
+  }
+  Technique {
+    VertexShader GLSL100 : Common/MatDefs/Misc/MyShader.vert
+    FragmentShader GLSL100 : Common/MatDefs/Misc/MyShader.frag
+    WorldParameters {
+      Time
+    }
+    RenderState {
+      Blend Alpha
+    }
+  } 
+}----
+
+== Material Instance files (J3M)
+
+In comparison to J3MD files, material instance (J3M) files are significantly simpler. In most cases, the user will not have to modify or create his/her own J3MD files.
+
+
+All J3M files begin with the word `Material` followed by the name of the material (once again, used for debugging only). Following the name, is a colon and the absolute asset path to the material definition (J3MD) file extended or implemented, followed by a curly-bracket.
+
+
+*Example:*
+
+
+[source]
+----Material MyGrass : Common/MatDefs/Misc/TestMaterial.j3md {----
+The material definition is a required component, depending on the material definition being used, the appearance and functionality of the material changes completely. Whereas the material definition provided the “logic for the material, the material instance provides the configuration for how this logic operates.
+
+
+The J3M file includes only a single structure; MaterialParameters, analogous to the same-named structure in the J3MD file. Whereas the J3MD file specified the parameter names and types, the J3M file specifies the values for these parameters. By changing the parameters, the configuration of the parent J3MD changes, allowing a different effect to be achieved.
+
+
+To specify a value for a parameter, one must specify first the parameter name, followed by a colon, and then followed by the parameter value. For texture parameters, the value is an absolute asset path pointing to the image file. Optionally, the path can be prefixed with the word “Flip in order to flip the image along the Y-axis, this may be needed for some models.
+
+
+*Example of a MaterialParameters block in J3M:*
+
+
+[source]
+----MaterialParameters {
+  m_Shininess : 20.0 
+}----[cols="2", options="header"]
+|===
+
+a|Param type
+a|Value example
+
+a|Int
+a|123
+
+a|Boolean
+a|true
+
+a|Float
+a|0.1
+
+a|Vector2
+a|0.1 5.6
+
+a|Vector3
+a|0.1 5.6 2.99
+
+a|Vector4=Color
+a|0.1 5.6 2.99 3
+
+a|Texture2D=TextureCubeMap
+a|Textures/MyTex.jpg
+
+|===
+
+}
+
+
+The formatting of the value, depends on the type of the value that was specified in the J3MD file being extended. Examples are provided for every parameter type:
+
+
+*Full example of a J3M*
+
+
+[source]
+----Material MyGrass : Common/MatDefs/Misc/TestMaterial.j3md { 
+  MaterialParameters {
+    m_MyTex : Flip Textures/GrassTex.jpg
+    m_Shininess : 20.0
+  }
+}----
+
+=== Java interface for J3M
+
+It is possible to generate an identical J3M file using Java code, by using the classes in the com.jme3.material package. Specifics of the link:http://jmonkeyengine.org/javadoc/com/jme3/material/Material.html[Material API] will not be provided in this document. The J3M file above is represented by this Java code:
+
+
+[source,java]
+----
+// Create a material instance
+Material mat = new Material(assetManager, "Common/MatDefs/Misc/
+    TestMaterial.j3md");
+// Load the texture. Specify "true" for the flip flag in the TextureKey
+Texture tex =
+assetManager.loadTexture(new TextureKey("Textures/GrassTex.jpg", true));
+// Set the parameters
+mat.setTexture("MyTex", tex);
+mat.setFloat("Shininess", 20.0f);
+----
+
+== Conclusion
+
+Congratulations on being able to read this entire document! To reward your efforts, jMonkeyEngine.com will offer a free prize, please contact Momoko_Fan aka “Kirill Vainer with the password “bananapie to claim.
+

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

@@ -0,0 +1,370 @@
+
+
+= Material Definition Properties
+
+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>>
+
+
+
+== All Materials Definition Properties
+
+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>>
+
+
+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.
+
+
+
+=== Unshaded Coloring and Textures
+
+jMonkeyEngine supports illuminated and unshaded Material Definitions.
+
+
+*  Phong Illuminated materials look more naturalistic.
+*  Unshaded materials look more abstract. 
+
+“Unshaded materials look somewhat abstract because they ignore lighting and shading. Unshaded Materials work even if the scene does not include a light source. These Materials can be single-colored or textured. For example, they are used for cards and tiles, for the sky, billboards and UI elements, for toon-style games, or for testing. 
+
+[cols="3", options="header"]
+|===
+
+a| Standard Unshaded Material Definition 
+a| Usage 
+<a| Material Parameters  
+
+a| Common/MatDefs/Misc/Unshaded.j3md 
+a| Standard, non-illuminated Materials. +
+Use this for simple coloring and texturing, glow, and transparency. +
+See also: <<jme3/beginner/hello_material#,Hello Material>> 
+a| *Texture Maps* +
+setTexture(“ColorMap, assetManager.loadTexture(“)); +
+ setBoolean(“SeparateTexCoord,true);  +
+setTexture(“LightMap, assetManager.loadTexture(“)); +
+*Colors* +
+setColor(“Color, ColorRGBA.White); +
+setBoolean(“VertexColor,true); +
+*Glow* +
+setTexture(“GlowMap, assetManager.loadTexture(“)); +
+setColor(“GlowColor, ColorRGBA.White); 
+
+|===
+
+Other useful, but less commonly used material definitions:
+
+[cols="3", options="header"]
+|===
+
+a| Special Unshaded Material Definitions 
+a| Usage 
+<a| Material Parameters  
+
+<a| Common/MatDefs/Misc/Sky.j3md            
+a| A solid skyblue, or use with a custom SkyDome texture. +
+See also: <<jme3/advanced/sky#,Sky>> 
+a| setTexture(“TextureCubeMap, assetManager.loadTexture(“)); +
+ setBoolean(“SphereMap,true); +
+setVector3(“NormalScale, new Vector3f(0,0,0)); 
+
+a| Common/MatDefs/Terrain/Terrain.j3md 
+a| Splat textures for e.g. terrains. +
+See also: <<jme3/beginner/hello_terrain#,Hello Terrain>> 
+a| setTexture(“Tex1, assetManager.loadTexture(“)); (red) +
+ setFloat(“Tex1Scale,1f); +
+ setTexture(“Tex2, assetManager.loadTexture(“)); (green) +
+ setFloat(“Tex2Scale,1f); +
+setTexture(“Tex3, assetManager.loadTexture(“)); (blue)  +
+ setFloat(“Tex3Scale,1f); +
+setTexture(“Alpha, assetManager.loadTexture(“)); 
+
+a|Common/MatDefs/Terrain/HeightBasedTerrain.j3md
+a|A multi-layered texture for terrains. +
+Specify four textures and a Vector3f describing the region in which each texture should appear: +
+X = start height, +
+Y = end height, +
+Z = texture scale. +
+Texture regions can overlap. +
+For example: Specify a seafloor texture for the lowest areas, +
+a sandy texture for the beaches, +
+a grassy texure for inland areas, +
+and a rocky texture for mountain tops.
+a| setFloat(“terrainSize,512f); +
+setTexture(“region1ColorMap, assetManager.loadTexture(“)); +
+setTexture(“region2ColorMap, assetManager.loadTexture(“)); +
+setTexture(“region3ColorMap, assetManager.loadTexture(“)); +
+setTexture(“region4ColorMap, assetManager.loadTexture(“)); +
+setVector3(“region1, new Vector3f(0,0,0)); +
+ setVector3(“region2, new Vector3f(0,0,0)); +
+ setVector3(“region3, new Vector3f(0,0,0)); +
+ setVector3(“region4, new Vector3f(0,0,0)); +
+*Settings for steep areas:* +
+setTexture(“slopeColorMap, assetManager.loadTexture(“)); +
+ setFloat(“slopeTileFactor,1f);
+
+<a| Common/MatDefs/Misc/Particle.j3md       
+a| Used with texture masks for particle effects, or for point sprites. +
+The Quadratic value scales the particle for perspective view (link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/core/com/jme3/effect/ParticleEmitter.java[formula]). +
+Does support an optional colored glow effect. +
+See also: <<jme3/beginner/hello_effects#,Hello Effects>> 
+a| setTexture(“Texture, assetManager.loadTexture(“)); +
+setTexture(“GlowMap, assetManager.loadTexture(“)); +
+setColor(“GlowColor, ColorRGBA.White); +
+ setFloat(“Quadratic,1f); +
+ setBoolean(“PointSprite,true); 
+
+|===
+
+
+=== Phong Illuminated
+
+jMonkeyEngine supports illuminated and unshaded Material Definitions.
+
+
+*  Phong Illuminated materials look more naturalistic.
+*  Unshaded materials look more abstract.
+
+Illuminated materials require a <<jme3/advanced/light_and_shadow#,light source>> added to at least one of their parent nodes! (e.g. rootNode.) Illuminated materials are darker on the sides facing away from light sources. They use Phong illumination model (default), or the Ward isotropic gaussian specular shader (WardIso) which looks more like plastic. They do not cast <<jme3/advanced/light_and_shadow#,drop shadows>> unless you use a FilterPostProcessor. 
+
+[cols="3", options="header"]
+|===
+
+a|Standard Illuminated Material Definition 
+a| Usage 
+a| Material Parameters 
+
+<a| Common/MatDefs/Light/Lighting.j3md      
+a| Commonly used Material with Phong illumination. +
+Use this material together with DiffuseMap, SpecularMap, BumpMap (NormalMaps, ParalaxMap) textures. +
+Supports shininess, transparency, and plain material colors (Diffuse, Ambient, Specular colors). +
+See also: <<jme3/beginner/hello_material#,Hello Material>> 
+<a| *Texture Maps* +
+setTexture(“DiffuseMap, assetManager.loadTexture(“)); +
+setBoolean(“UseAlpha,true);footnote:[UseAlpha specifies whether DiffuseMap uses the alpha channel]  +
+setTexture(“NormalMap, assetManager.loadTexture(“)); +
+setBoolean(“LATC,true); footnote:[LATC Specifies whether NormalMap is BC5/ATI2n/LATC/3Dc-compressed]  +
+setTexture(“SpecularMap, assetManager.loadTexture(“)); +
+ setFloat(“Shininess,64f); +
+setTexture(“ParallaxMap, assetManager.loadTexture(“)); +
+setTexture(“AlphaMap, assetManager.loadTexture(“)); +
+ setFloat(“AlphaDiscardThreshold,1f); +
+setTexture(“ColorRamp, assetManager.loadTexture(“)); +
+*Glow* +
+setTexture(“GlowMap, assetManager.loadTexture(“)); +
+setColor(“GlowColor, ColorRGBA.White); +
+*Performance and quality* +
+setBoolean(“VertexLighting,true); +
+  setBoolean(“UseVertexColor,true); +
+ setBoolean(“LowQuality,true); +
+ setBoolean(“HighQuality,true); +
+*Material Colors* +
+ setBoolean(“UseMaterialColors,true); +
+setColor(“Diffuse, ColorRGBA.White); +
+ setColor(“Ambient, ColorRGBA.White); +
+setColor(“Specular, ColorRGBA.White); +
+*Tangent shading:* +
+ setBoolean(“VTangent,true); +
+ setBoolean(“Minnaert,true);footnote:[Minnaert is a shader type.] +
+setBoolean(“WardIso,true);footnote:[WardIso is a shader type.]  
+
+|===
+[cols="3", options="header"]
+|===
+
+a|Special Illuminated Material Definitions 
+a| Usage 
+a| Material Parameters 
+
+a|Common/MatDefs/Terrain/TerrainLighting.j3md
+a|Same kind of multi-layered splat texture as Terrain.j3md, but with illumination and shading. +
+Typically used for terrains, but works on any mesh. +
+For every 3 splat textures, you need one alpha map. +
+You can use a total of 11 texture maps in the terrain's splat texture: +
+Note that diffuse and normal maps all count against that. +
+For example, you can use a maximum of 9 diffuse textures, two of which can have normal maps; +
+or, five textures with both diffuse and normal maps.
+a|*Texture Splat Maps* +
+ setTexture(“DiffuseMap, assetManager.loadTexture(“)); +
+ setFloat(“DiffuseMap_0_scale,1f); +
+setTexture(“NormalMap, assetManager.loadTexture(“)); +
+setTexture(“DiffuseMap_1, assetManager.loadTexture(“)); +
+ setFloat(“DiffuseMap_1_scale,1f); +
+setTexture(“NormalMap_1, assetManager.loadTexture(“)); +
+setTexture(“DiffuseMap_2, assetManager.loadTexture(“)); +
+ setFloat(“DiffuseMap_2_scale,1f); +
+setTexture(“NormalMap_2, assetManager.loadTexture(“)); +
+setTexture(“DiffuseMap_3, assetManager.loadTexture(“)); +
+ setFloat(“DiffuseMap_3_scale,1f); +
+setTexture(“NormalMap_3, assetManager.loadTexture(“)); +
+etc, up to 11. +
+*Alpha Maps* +
+setTexture(“AlphaMap, assetManager.loadTexture(“)); +
+setTexture(“AlphaMap_1, assetManager.loadTexture(“)); +
+setTexture(“AlphaMap_2, assetManager.loadTexture(“)); +
+*Glowing* +
+setTexture(“GlowMap, assetManager.loadTexture(“)); +
+setColor(“GlowColor, ColorRGBA.White); +
+*Miscellaneous* +
+setColor(“Diffuse, ColorRGBA.White); +
+setColor(“Ambient, ColorRGBA.White); +
+setFloat(“Shininess,64f); +
+setColor(“Specular, ColorRGBA.White); +
+setTexture(“SpecularMap, assetManager.loadTexture(“)); +
+setBoolean(“WardIso,true); +
+ setBoolean(“useTriPlanarMapping,true); +
+ setBoolean(“isTerrainGrid,true); 
+
+<a| Common/MatDefs/Light/Reflection.j3md    
+a| Reflective glass material with environment map (CubeMap/SphereMap). See also: link:http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/texture/TestCubeMap.java[TestCubeMap.java] 
+a| setTexture(“Texture, assetManager.loadTexture(“)); +
+ setBoolean(“SphereMap,true); 
+
+|===
+
+
+=== Other: Test and Debug
+[cols="2", options="header"]
+|===
+
+<a| Material Definition                     
+a| Usage 
+
+<a| Common/MatDefs/Misc/ShowNormals.j3md    
+a| A color gradient calculated from the model's surface normals. You can use this built-in material to debug the generation of normals in meshes, to preview models that have no material and no lights, or as fall-back default material. This built-in material has no parameters. 
+
+|===
+
+
+== RenderStates
+
+
+=== Transparency
+[cols="3", options="header"]
+|===
+
+a|Material Option
+a|Description
+a|Example
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.Off);
+a|This is the default, no transparency.
+a|Use for all opaque objects like walls, floors, people…
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.Alpha);
+a|Interpolates the background pixel with the current pixel by using the current pixel's alpha.
+a|Use this for normal every-day translucency: Frosted window panes, ice, glass, alpha-blended vegetation textures… 
+
+a|getAdditionalRenderState().setDepthWrite(false);
+a|Disables writing of the pixel's depth value to the depth buffer.
+a|Use this on Materials if you have several transparent/translucent objects obscuring one another, but you want to see through both.
+
+a|getAdditionalRenderState().setAlphaFallOff(0.5f); +
+getAdditionalRenderState().setAlphaTest(true)
+a|Enables Alpha Testing with a “AlphaDiscardThreshold in the AlphaMap.
+a|Activate Alpha Testing for (partially) *transparent* objects such as foliage, hair, etc. +
+Deactivate Alpha Testing for gradually *translucent* objects, such as colored glass, smoked glass, ghosts.
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.Additive);
+a|Additive alpha blending adds colors in a commutative way, i.e. the result does not depend on the order of transparent layers, since it adds the scene's background pixel color to the current pixel color. This is useful if you have lots of transparent textures overlapping and don't care about the order. +
+*Note:* Viewed in front of a white background, Additive textures become fully transparent! 
+a| This is the default for Particle.j3md-based textures that have a black color background. 
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.AlphaAdditive);
+a|Same as “Additive, except first it multiplies the current pixel color by the pixel alpha.
+a|This can be used for particle effects that have alpha as background. 
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.Color);
+a|Blends by color.
+a|Generally useless.
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.Modulate);
+a|Multiplies the background pixel by the current pixel.
+a|?
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.ModulateX2);
+a|Same as “Modulate, except the result is doubled.
+a|?
+
+a|getAdditionalRenderState().setBlendMode(BlendMode.PremultAlpha);
+a|Pre-multiplied alpha blending. E.g. if the color of the object has already been multiplied by its alpha, this is used instead of “Alpha blend mode.
+a|For use with Premult Alpha textures.
+
+|===
+
+If the DiffuseMap has an alpha channel, use:
+
+
+[source,java]
+----mat.setBoolean("UseAlpha",true);----
+Later, put the Geometry (not the Material!) in the appropriate render queue
+
+
+*  
+[source,java]
+----geo.setQueueBucket(Bucket.Translucent);----
+*  
+[source,java]
+----geo.setQueueBucket(Bucket.Transparent);----
+
+
+=== Culling
+[cols="3", options="header"]
+|===
+
+a|Material Option
+a|Usage
+a|Example
+
+a|getAdditionalRenderState().setFaceCullMode(FaceCullMode.Back); 
+a|Activates back-face culling. Mesh faces that are facing away from the camera are not rendered, which saves time. *Backface culling is activated by default as a major optimization.* 
+a|The invisible backsides and insides of models are not calculated. 
+
+a|getAdditionalRenderState().setFaceCullMode(FaceCullMode.Off); 
+a|No meshes are culled. Both mesh faces are rendered, even if they face away from the camera. Slow.
+a|Sometimes used to debug custom meshes if you messed up some of the polygon sides, or for special shadow effects.
+
+a|getAdditionalRenderState().setFaceCullMode(FaceCullMode.Front); 
+a|Activates front-face culling. Mesh faces facing the camera are not rendered.
+a|No example – Typically not used because you wouldn't see anything meaningful.
+
+a|getAdditionalRenderState().setFaceCullMode(FaceCullMode.FrontAndBack)
+a|Culls both backfaces and frontfaces.
+a|Use this as an efficient way to make an object temporarily invisible, while keeping all its other in-game properties (such as node attachment, collision shapes, interactions, etc) active.
+
+|===
+
+
+=== Miscellaneous
+[cols="3", options="header"]
+|===
+
+a|getAdditionalRenderState().setColorWrite(false);
+a|Disable writing the color of pixels.
+a|Use this together with setDepthWrite(true) to write pixels only to the depth buffer, for example. 
+
+a|getAdditionalRenderState().setPointSprite(true);
+a|Enables point-sprite mode, e.g. meshes with “Mode.Points will be rendered as textured sprites. Note that gl_PointCoord must be set in the shader.
+a|Point sprites are used internally for hardware accelerated particle effects.
+
+a|getAdditionalRenderState().setPolyOffset();
+a|Enable polygon offset.
+a|Use this when you have meshes that have triangles really close to each over (e.g. link:http://en.wikipedia.org/wiki/Coplanarity[Coplanar]), it will shift the depth values to prevent link:http://en.wikipedia.org/wiki/Z-fighting[Z-fighting].
+
+|===
+
+*Related Links*
+
+
+*  <<jme3/advanced/material_specification#,Developer specification of the jME3 material system (.j3md,.j3m)>>
+<tags><tag target="material" /><tag target="texture" /><tag target="MatDefs" /><tag target="light" /><tag target="culling" /><tag target="RenderStates" /><tag target="documentation" /></tags>

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

@@ -0,0 +1,163 @@
+
+
+= Polygon Meshes
+
+
+image::jme3/dolphin-mesh.png[dolphin-mesh.png,with="",height="",align="right"]
+
+
+
+All visible game elements in a scene, whether it is a Model or a Shape, are made up of polygon meshes. JME3 has a com.jme3.scene.Mesh class that represents all meshes.
+
+
+*  Meshes are made up of triangles: `getTriangleCount(…)` and `getTriangle(…)`
+*  Each mesh has a unique ID: `getId()`
+*  Meshes have transformations: Location (local translation), rotation, scale.
+*  Meshes have a bounding volume. jME3 can detect intersections (that is, non-physical collisions) between meshes, or between meshes and 2D elements such as rays: `collideWith()`.
+*  Meshes are locked with `setStatic()` and unlocked with `setDynamic()`. 
+**  Static Meshes cannot be modified, but are more optimized and faster (they can be precalculated). 
+**  Dynamic Meshes can be modified live, but are not optimized and slower. 
+
+
+You have several options when <<spatial#,creating Geometries from meshes>>:
+
+
+*  Use built-in <<shape#,Shape>>s as meshes; 
+*  Load <<3d_models#,3D models>> (that is, meshes created in external applications); or 
+*  Create free-form <<jme3/advanced/custom_meshes#,custom meshes>> programmatically. 
+
+
+== Vertex Buffer
+
+The VertexBuffer contains a particular type of geometry data used by Meshes. Every VertexBuffer set on a Mesh is sent as an attribute to the vertex shader to be processed.
+
+
+
+=== Mesh Vertex Buffers
+[cols="2", options="header"]
+|===
+
+a|Vertex Buffer Type
+a|Description
+
+a|Type.Position 
+a|Position of the vertex (3 floats)
+
+a|Type.Index 
+a| Specifies the index buffer, must contain integer data.
+
+a|Type.TexCoord 
+a| Texture coordinate
+
+a|Type.TexCoord2 
+a| Texture coordinate #2
+
+a|Type.Normal 
+a| Normal vector, normalized.
+
+a|Type.Tangent 
+a| Tangent vector, normalized.
+
+a|Type.Binormal 
+a| Binormal vector, normalized.
+
+a|Type.Color 
+a| Color and Alpha (4 floats)
+
+a|Type.Size 
+a|The size of the point when using point buffers.
+
+a|Type.InterleavedData 
+a| Specifies the source data for various vertex buffers when interleaving is used.
+
+a|Type.BindPosePosition 
+a| Inital vertex position, used with animation.
+
+a|Type.BindPoseNormal 
+a| Inital vertex normals, used with animation
+
+a|Type.BoneWeight 
+a| Bone weights, used with animation
+
+a|Type.BoneIndex 
+a| Bone indices, used with animation
+
+|===
+
+
+=== Mesh Properties
+[cols="2", options="header"]
+|===
+
+a|Mesh method
+a|Description
+
+a|setLineWidth(1)
+a|the thickness of the line if using Mode.Lines
+
+a|setPointSize(4.0f)
+a|the thickness of the point when using Mode.Points
+
+a|setBound(boundingVolume)
+a|if you need to specifiy a custom optimized bounding volume
+
+a|setStatic()
+a|Locks the mesh so you cannot modify it anymore, thus optimizing its data (faster).
+
+a|setDynamic()
+a|Unlocks the mesh so you can modified it, but this will un-optimize the data (slower).
+
+a|setMode(Mesh.Mode.Points)
+a|Used to set mesh rendering modes, see below.
+
+a|getId()
+a|returns the Mesh ID
+
+a|getTriangle(int,tri)
+a|returns data of triangle number `int` into variable `tri`
+
+a|scaleTextureCoordinates(Vector2f)
+a|How the texture will be stretched over the whole mesh.
+
+|===
+
+
+=== Mesh Rendering Modes
+[cols="2", options="header"]
+|===
+
+a|Mesh Mode
+a|Description
+
+a|Mesh.Mode.Points
+a|Show only corner points (vertices) of mesh
+
+a|Mesh.Mode.Lines
+a|Show lines (edges) of mesh
+
+a|Mesh.Mode.LineLoop
+a|?
+
+a|Mesh.Mode.LineStrip
+a|?
+
+a|Mesh.Mode.Triangles
+a|?
+
+a|Mesh.Mode.TriangleStrip
+a|?
+
+a|Mesh.Mode.TriangleFan
+a|?
+
+a|Mesh.Mode.Hybrid
+a|?
+
+|===
+
+
+=== Level of Detail
+
+Optionally, custom meshes can have a LOD (level of detail optimization) that renders more or less detail, depending on the distance of the mesh from the camera. You have to specify several vertex buffers, one for each level of detail you want (very far away with few details, close up with all details, and something in the middle). Use `setLodLevels(VertexBuffer[] lodLevels)`. 
+
+<tags><tag target="spatial" /><tag target="node" /><tag target="mesh" /><tag target="geometry" /><tag target="scenegraph" /></tags>

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

@@ -0,0 +1,25 @@
+
+
+= User Guide for MonkeyBrains
+
+MonkeyBrains is a sophisticated AI Engine for jMonkeyEngine. It uses an agent framework to wrap human and AI controlled characters in plugin-based AI algorithms so that different each game can pick out whichever AI techniques fits best.
+Download MonkeyBrains from the GitHub link:https://github.com/QuietOne/MonkeyBrains[repository].
+
+
+
+== MonkeyBrains Wiki
+
+User guide for MonkeyBrains is moved to link:https://github.com/QuietOne/MonkeyBrains/wiki[MonkeyBrains Wiki]
+
+
+
+== Working games:
+
+For more examples of working games built with MonkeyBrains see: link:https://github.com/QuietOne/MonkeyBrainsDemoGames[https://github.com/QuietOne/MonkeyBrainsDemoGames]
+
+
+
+== Suggestions and questions:
+
+If you have suggestion or any questions, please see forum: link:http://hub.jmonkeyengine.org/forum/board/projects/monkeybrains/[http://hub.jmonkeyengine.org/forum/board/projects/monkeybrains/]
+