= atomcore
:author: 
:revnumber: 
:revdate: 2016/03/17 20:48
:relfileprefix: ../../../
:imagesdir: ../../..
ifdef::env-github,env-browser[:outfilesuffix: .adoc]



== 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


[NOTE]
====
This is so important to mention that every techs Atom framework are around Bean/ POJO technologies. 
====


In <<jme3/advanced/atom_framework/atomcore/beans#,AtomCore Bean>> are leverage in a few ways:

*  Modeling
*  Generating
*  Binding
*  Mapping / Morphing
*  Instropecting
*  Managed


===== Attend Cycle

In JME3 we almost see the things work like this, the “almighty” Cycle:

<<jme3/advanced/update_loop#,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


[IMPORTANT]
====
We (forum members) and game devs all over the world also have controversial conversations, debates and judgments about it. But I have to admit its an undeniable trend game maker all head into in the next decade as the revolution of GPU, CPU employ data oriented approach and batch processing a lot.
====


You can read about Component base solutions and architecture here:

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. 


[WARNING]
====
Note: This package contains a lot of stuff borrowed from libraries and should be clean up. Do not rely too much in this library!
====



==== 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
