Initial commit for documentation of Limon Engine

AUTHORS.rst

@@ -0,0 +1,5 @@
+Authors
+-------
+
+* Engin Manap
+* Alper Tekinalp

README.rst

@@ -0,0 +1,28 @@
+
+Welcome to Limon Engine's documentation!
+========================================
+
+Limon is a multi platform 3D game engine mainly focusing on first person games. Focus of its development is ease of use and ease of study. It has builtin editor for maps, animations and GUIs.
+
+Prebuilt binaries for Windows, Linux and MacOS can be `found here <https://github.com/enginmanap/limonEngine/releases>`_
+
+If you want to check out what Limon engine is and can do, you can check out about.
+
+The documentation is separated in three major sections:
+
+1. How to use the engine and build in editor to create games.
+2. Extending capabilities using Limon API.
+3. Engine architecture and internals.
+
+Contribute
+----------
+
+If you are having issues, or if you think some awesome feature is missing, please let us know using the issue tracker.
+
+- Issue Tracker: https://github.com/enginmanap/limonEngine/issues
+- Source Code: https://github.com/enginmanap/limonEngine
+
+License
+-------
+
+The project is licensed under the LGPL license.

docs/GettingStarted.rst

@@ -0,0 +1,40 @@
+===============
+Getting Started
+===============
+
+Acquiring Limon Engine
+======================
+
+You can download the prebuilt binaries from `github releases <https://github.com/enginmanap/limonEngine/releases>`_, or you can build the engine for yourself.
+
+The engine comes with a test map, and launches it by default, so you can launch the engine and start working. If you are not interested in building on your own, you can continue to :ref:`UsingBuiltinEditor`.
+
+Building
+========
+
+Limon uses c++14, so a supporting c++ compiler is required. GCC 7.2 to 8.2 are tested. Building Limon also requires the libraries listed below:
+
+* assimp
+* bullet
+* sdl2
+* sdl2-image
+* freetype6
+* tinyxml2
+* glew
+* glm
+* tinyxml2
+
+If you are using Ubuntu, you can use the line below to install the required libraries:
+::
+   sudo apt-get install libassimp-dev libbullet-dev libsdl2-dev libsdl2-image-dev libfreetype6-dev libtinyxml2-dev libglew-dev build-essential libglm-dev libtinyxml2-dev
+
+Limon Engine uses cmake as build system, if all the libraries are installed and cmake can find them, invoking cmake should build the engine.
+
+Release source contains a directory, in that directory, call these commands:
+::
+    mkdir build
+    cd build
+    cmake ../
+
+after that, depending on the system, either the executable binaries, or appropriate build system files like automake should be generated. If that is the case, use the build system for your installation to compile final binaries.
+

docs/Makefile

@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/UsingTheEditor.rst

@@ -0,0 +1,144 @@
+.. _UsingBuiltinEditor:
+
+====================
+Using Builtin Editor
+====================
+
+Builtin editor can be used to create maps, interfaces and menus. 3D and 2D components share the tooling, and they can be mixed and matched, meaning it is possible to build 3d world as background in menus, or using menus with in game play.
+
+
+Editor Basics
+#############
+
+The editor has 3 main windows. By default left of the screen is object properties, right is world properties and bottom is animation sequencer. As expected you can drag and drop and resize the windows. If no object is selected, only the world properties window is visible. Animation sequencer is visible only when creating an animation.
+
+.. figure:: _static/media/images/editor-world-withAnimation.jpg
+    :align: center
+
+World Editor Details
+####################
+
+World editor loads up with almost all the features hidden by the titles. The fresh loaded window looks like this:
+
+.. figure:: _static/media/images/editor-world-nonSelected.jpg
+    :align: center
+
+There are 2 main types of elements that can be used to build the world.
+
+* 3D Objects
+* GUI elements
+
+To make selection easier, click to select doesn't work for both types at the same time. At launch you can select Objects. If you click "Switch to GUI selection mode", you will be able to select GUI elements, but not Objects. The button will be replaced by "Switch to World selection mode".
+
+Adding 3D objects
+_________________
+
+There are 2 types of 3D object you can add to the world.
+
+* Models
+* Trigger volumes
+
+.. figure:: _static/media/images/editor-addObject.png
+    :align: center
+
+Models list is loaded from "./Data/Models/" directory. You can select a model from the drop down list. When mass is set to 0, the object will be marked "static" by physics system. This means the model will not be able to move, outside of the editor. It is the default setting, to be used for building the world. Any other value will mark the object as "dynamic", meaning the objects movements will be governed by physics engine.
+
+If an object is already selected, "Copy position offsets" settings and "Copy Selected Objects" button is shown. These are used to copy selected object, with given offsets. Offsets can be used to make copy automatically position so a grid or a wall can be created.
+
+.. figure:: _static/media/images/physics-hull_vs_full.png
+    :align: center
+
+    Dynamic object have Convex hulls (left), while static objects have full mesh as collision mesh (right).
+
+.. figure:: _static/media/images/physics-hull_vs_baked.png
+    :align: center
+
+    Static objects can use baked collision meshes(right)
+
+.. figure:: _static/media/images/physics-animated.png
+    :align: center
+
+    animated object has per bone convex hulls
+
+Dynamic objects physical representations are simplified automatically. For inanimate models, the simplified representation will be a convex hull. This means the cavities, crannies etc. will not be calculated for them. For animated models, each vertex will be assigned the bone that has the most weight on it, and for each bone a convex hull will be created. It means separate members of the model will be calculates as such.
+
+Static object have a full mesh representing physical object. It is possible to replace this with a simplified mesh. To do so, bake meshes with names prefixed with "UCX_". They will be used for physics.
+
+.. note::
+    Models with animations, both from the asset itself and custom using the editor are considered "kinematic" It means the object is allowed to move, but the movement is not governed by physics engine. Those types of objects can't be moved by physical interactions like pushing or pulling, but they can effect physical objects.
+
+.. note::
+    Because physical representation is dependent on the mass, mass setting cant be changed once an model is added to the world. If you need to change the mass, remove and add again.
+
+Add Trigger Volume button will create an empty cube. That cube can be used to trigger custom code paths. The details are at :ref:`TriggerVolumes`.
+
+Adding GUI Elements
+___________________
+
+GUI elements are rendered using layers. Each layer has a level, with default layer at level 0. Bigger levels are higher up, meaning when overlapped, the one with the higher level will be rendered.
+
+.. figure:: _static/media/images/editor-addGUI.png
+    :align: center
+
+You can add the following using the editor:
+
+* Layer
+* Text
+* Image
+* Button
+
+Add GUI layer menu allows you to add a new layer, with set level.
+
+To add GUI text, you need to set the font, font size and name. The layer of the text can be selected from the drop down.
+
+.. note::
+    Since the font renderer is building the text using the set font size. GUI texts are not scalable.
+
+To add GUI Image, you need to set the name and image files path relative to the engine. The layer of the image can be selected from the drop down.
+
+To add GUI Button, you need to set the name, and normal image file path relative to the engine.
+
+The Button can be interactive, depending on the player state. If player is set interactive, the following logic is used:
+
+#. If The button doesn't have an trigger, and have a disabled image set, the disabled image will be shown.
+#. If on click image is set, and mouse is down over the button, on click image is shown. Also Trigger will be run. For details, please check :ref:`Triggers`.
+#. If on hover image is set, and mouse cursor is over the button, that image will be shown.
+#. If all else were wrong, the normal image will be shown.
+
+The layer of the button can be selected from the drop down.
+
+Setting Up Map Properties
+_________________________
+
+.. figure:: _static/media/images/editor-world.png
+    :align: center
+
+You can set the following using the world editor.
+
+#. You can add triggers to run after the world load finished. For details please check  :ref:`Triggers`.
+#. You can set the music that will be playing after map load finished.
+#. You can set what kind of interaction will be possible at the launch of the map. Possible values are
+  * Physical: Normal Player for game play
+  * Debug: The player that controls exactly like physical, but doesn't interact with physics, so can fly and walkthrough objects. Also renders physics meshes, GUI borders and AI walk grid to allow debugging issues.
+  * Editor: Builtin editor.
+  * Menu: Menu interaction is allowed, and animation, AI and Physics subsystems are stopped.
+#. You can set what should be done when player press ESC key.
+  * Quit Game: exits the game immediately without asking for a verification
+  * Return Previous: Loaded maps list is kept within the engine. This option returns the world before current one. If this is the first world, or this world is loaded with force new directive, this option does nothing.
+  * Load World: This option add a new text input to the editor. The map at the path entered will be loaded if not already, and the current map will switch to the entered one.
+
+.. warning::
+    For a game release, Debug and Editor types should be removed. Those types are only for development purposes.
+
+Other editor controls
+_____________________
+
+.. figure:: _static/media/images/editor-others.png
+    :align: center
+
+Loaded custom animations will be listed under custom animations for convenience. You can load other custom animation by entering the file path.
+
+Saving the map
+______________
+
+The map will be saved at the path when save world is clicked, overriding if it already exists.