[add] docs progress

.gitignore

@@ -31,3 +31,4 @@ iolite_plugins/windows/*.ilk
 !iolite_plugins/**/lua51.*
 
 hohenzollern_castle_and_kingdom.vox
+.DS_Store

iolite_docs/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "voxel"
+    ]
+}

iolite_docs/.vscode/tasks.json

@@ -0,0 +1,17 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build Docs",
+            "type": "shell",
+            "command": "make html",
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

iolite_docs/api/c.rst

@@ -3,9 +3,19 @@
 Native C API
 ============
 
-.. note:: The C API is available as a `single documented header file <https://github.com/MissingDeadlines/iolite/blob/main/iolite_c_api/iolite_api.h>`_ in our public GitHub repository.
-
-Writing your first native plugin for IOLITE is easy. For further instructions, please refer to the guide :ref:`writing plugins`.
+This section shows the API header file and serves as a reference for IOLITE's C API. The header file is dependency-free, kept as minimal as possible, and can be compiled with all common C or C++ compilers.
+
+All functions, data structures, and interfaces are documented in the header file itself.
+
+For detailed instructions on writing plugins and the general usage of the API, please header over to the :ref:`writing plugins` section to get started.
+
+.. note:: 
+  All versions of IOLITE's C API header file are available `in our public GitHub repository <https://github.com/MissingDeadlines/iolite/blob/main/iolite_c_api/iolite_api.h>`_. 
+.. warning::
+  Please make sure to use a header file that matches the binary release of IOLITE you are using for your project. All IOLITE binary releases come with an according tag in the repository.
+
+iolite_api.h
+------------
 
 .. literalinclude:: ../../iolite_c_api/iolite_api.h
   :language: c

iolite_docs/conf.py

@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'IOLITE - Voxel Game Engine'
+project = 'IOLITE'
 copyright = '2023, Missing Deadlines. All Rights Reserved'
 author = 'Missing Deadlines (Benjamin Wrensch)'
 

iolite_docs/engine/intro.rst

@@ -95,19 +95,19 @@ The app metadata allows you to adjust basic properties like your application's n
 
 Here's an overview of all the different parameters:
 
-application_name (String)
+application_name ``String``
    The name of your application.
-organization_name (String)
+organization_name ``String``
    The name of your organization (if any).
-version_string (String)
+version_string ``String``
    Version string following the `Semantic Versioning <https://semver.org/>`_ scheme.
-data_sources (Array of strings)
+data_sources ``Array of strings``
    The data sources used for your project. Data sources are loaded in the provided order. The engine starts searching for files in the first data sources and, if the file in question is found, skips searching all the other data sources.
-initial_world (String)
+initial_world ``String``
    The initial world to load after startup.
-initial_game_state (String)
+initial_game_state ``String``
    The initial game state to activate after startup. It can be either ``Editing`` for the editor or ``Main`` to start the application in game mode directly.
-disable_telemetry (Boolean)
+disable_telemetry ``Boolean``
    Set this to ``true`` to disable the collection of anonymous telemetry data.
 
 These additional settings are available in the PRO version of IOLITE:

iolite_docs/engine/subsystems/sound.rst

@@ -42,32 +42,32 @@ To create a sound effect, create a ``my_sound_effect.effect.json`` file in the `
    
 A single effect supports the following parameters:
 
-audio_samplers (Array of audio samplers)
+audio_samplers ``Array of audio samplers``
    The audio samplers for this effect. A single effect can play multiple samplers at the same time.
-volume (Float, optional)
+volume ``Float, optional``
    The volume for this sound effect. Use a value of ``0.0`` for a muted and a value of ``1.0`` for the loudest sound effect.
-looping (Boolean, optional)
+looping ``Boolean, optional``
    Set to ``true`` to automatically restart the effect instance when it has finished playing. Great for background music or ambient effects.
-spatial (Boolean, optional)
+spatial ``Boolean, optional``
    Set to ``true`` for spatial/3D sound effects. Spatial effects have a position in 3D space and change their volume depending on the listener's position.
-spatial_size (Float, optional)
+spatial_size ``Float, optional``
    The spatial size of the effect. If the distance to the listener is less than this value, the effect fades into a non-spatial sound effect.
-dist_att_min (Float, optional)
+dist_att_min ``Float, optional``
    The minimum distance attenuation volume. Sound effects will never get quieter than this volume value when attenuated based on the distance to the listener.
-dist_att_power (Float, optional)
+dist_att_power ``Float, optional``
    Specifies how quickly a sound effect is attenuated based on the distance to the listener.
-dist_att_range (Float, optional)
+dist_att_range ``Float, optional``
    The range world units in which the distance attenuation operates. Effects out of this range will be attenuated to the volume specified by the ``dist_att_min`` parameter.
 
 Audio samplers support the following parameters:
 
-file_names (Array of strings)
+file_names ``Array of strings``
    List of file names, including the file extension, of the audio files to play for this sampler. If more than one file name is provided, a random file is picked every time the effect is restarted.
-volume (Float, optional)
+volume ``Float, optional``
    The volume for this sampler. Behaves the same as the global volume for the effect.
-timeline_offset (Float, optional)
+timeline_offset ``Float, optional``
    The position on the effect's timeline in seconds when this sampler should start playing.
-pitch (Array of floats, optional)
+pitch ``Array of floats, optional``
    Randomly alters the pitch in the provided interval. Requires exactly two values in the array, which can be positive or negative. The first represents the minimum, and the second the maximum relative pitch change in cents.
 
 Playing sound effects

iolite_docs/faq.rst

@@ -1,7 +1,7 @@
 .. _faq:
 
-⁉️ Frequently asked questions
-=============================
+️❓Frequently asked questions
+============================
 
 Here's a collection of frequently asked questions. Make sure to go through each one if you're encountering an issue. Chances are high that it is already known and documented here.
 

iolite_docs/getting_started/index.rst

@@ -1,27 +1,33 @@
-👀 Getting Started
-===================
+👀 Getting started
+==================
 
 This section contains installation instructions and guides to get you started.
 
 Installing IOLITE
 -----------------
 
-Download a release from the `landing page <https://iolite-engine.com>`_ or, if you have subscribed to IOLITE PRO, from the `subscriber area <https://iolite-engine.com/subscribers>`_ and unzip it. Finally, launch the IOLITE executable. That's it. 🙂 
+.. note:: IOLITE is shipped with a an **installer** that can, in addition to installing the binary distribution, automatically download the latest versions of the plugins and samples from our repository.
 
-If you encounter an issue when running IOLITE, please consult the section :ref:`faq`. If you are unable to solve the issue, please follow the steps depicted in :ref:`reporting_issues`.
+.. warning:: The installer is currently only for Windows builds and Linux builds have to be set up manually. This includes unzipping the binary distribution and optionally downloading the latest plugin binaries and samples from the repository.
+
+1. Download the latest stable or beta release from the `landing page <https://iolite-engine.com>`_ or, if you have subscribed to IOLITE PRO, from the `subscriber area <https://iolite-engine.com/subscribers>`_
+
+2. Execute the installer, select the desired components and an installation directory, and execute IOLITE from the installation directory afterwards.
+
+.. note:: If you encounter an issue when running IOLITE, please consult the section :ref:`faq`. If you are unable to solve the issue, please follow the steps depicted in :ref:`reporting_issues`.
 
 Beta releases
 -------------
 
 Beta releases are released in between main releases for PRO subscribers. Please consider the following when working with a beta release of IOLITE:
 
-.. important:: Beta releases are released more frequently and contain the latest features, but they can be a little less stable.
+.. important:: Betas are released more frequently and contain the latest features, but they can be a little less stable. Frequent changes to the API are expected.
 
-- Please switch to the ``develop`` branch in our public GitHub repository and search for a tag matching the version of IOLITE you are using
-- Please ensure that you are using a matching version of the open-source plugins. Due to potential API changes, there are separate plugin releases available for the beta versions of IOLITE
+1. Switch to the ``develop`` branch in our public GitHub repository and search for a tag matching the version of IOLITE you are using
+2. Ensure that you are using a matching version of the open-source plugins. Due to potential API changes, there are separate GitHub releases available for the beta versions of IOLITE
 
-Telemetry (Usage statistics)
-----------------------------
+Telemetry
+---------
 
 IOLITE, by default, gathers some elementary **anonymous usage statistics** to aid the development.
 
@@ -46,37 +52,4 @@ You can turn off the telemetry system at any time by adding the following member
 
 .. code-block:: json
    
-  "disable_telemetry": true
-
-Writing your first "Hello, World!" script in Lua
-------------------------------------------------
-
-This short tutorial serves as a step-by-step guide to writing your first Lua script in IOLITE.
-
-.. important::
-  This guide requires the latest version of the Lua plugin for IOLITE to be installed. Please check the section :ref:`working_with_plugins` for more details.
-
-Open up your favorite code editor and create a new file. Copy and paste the following Lua script, which logs two strings to the console:
-
-.. code-block:: lua
-
-  Log.load()
-
-  -- Logs each time the script gets (re-)loaded
-  Log.log_info("Hello world! Script loaded!")
-
-  function OnActivate(entity)
-    -- Logs once the component becomes active
-    Log.log_info("Hello world! Component active!")
-  end
-
-After that, continue with the following steps:
-
-1. Store the script in ``default/media/scripts/`` and name it ``hello_world.lua``
-2. Open up IOLITE, ensure that the editor is active, and head over to the *World Inspector*
-3. Create a new entity with a script component attached to it
-4. In the property inspector, set the ``Script`` property to ``hello_world`` (without the extension)
-5. Switch to the game mode by clicking ``[Game Mode]`` in the menu bar
-6. Press ``[F2]`` to open up the console and check if the strings have been logged successfully
-
-Keep IOLITE open and modify the strings passed to the log functions. Every time you save the script, it triggers a hot reload. Notice how the global log call gets executed while the call in ``OnActivate`` is not. This call can be, e.g., triggered by switching back and forth between the game mode and the editor; the editor can be activated using ``[F3]``.
+  "disable_telemetry": true

iolite_docs/index.rst

@@ -38,8 +38,11 @@
 
   api
 
-
 IOLITE 0.5 documentation
 ========================
-
-Welcome to the documentation of IOLITE, the voxel-powered game engine. If you're new here, we recommend directly heading to the :ref:`introduction section <intro>`.
+
+Welcome to the documentation of IOLITE, the voxel-powered game engine.
+
+If you're new here, we recommend directly heading to the :ref:`introduction section <intro>`.
+
+.. note:: This documentation is considered a work in progress and is updated frequently.

iolite_docs/intro.rst

@@ -1,7 +1,7 @@
 .. _intro:
 
-🧊 IOLITE - Voxel Game Engine
-==============================
+🧊 About IOLITE
+===============
 
 IOLITE is a real-time voxel game engine powered by path tracing. Create the game of your dreams in highly detailed and dynamic worlds using the embedded editor and C/C++ or Lua.
 

iolite_docs/plugins/creating_plugins.rst

@@ -5,9 +5,9 @@ Writing plugins using the native C/C++ API
 
 IOLITE's C/C++ API offers the possibility to create highly modular engine and editor plugins in C, C++, or any other language that supports C bindings.
 
-.. important:: The API documentation is provided via the header file itself.
+.. important:: The API documentation is provided via the header file itself, see :ref:`api_c` for details.
 
-.. important:: Native plugins are a feature of IOLITE PRO. You're free to evaluate plugins in the free version, but loading non-default plugins will add a watermark to the editor and game.
+.. warning:: Native plugins are a feature of IOLITE PRO. You're free to evaluate plugins in the free version, but loading non-default plugins will add a watermark to the editor and game.
 
 Writing a simple plugin
 ^^^^^^^^^^^^^^^^^^^^^^^

iolite_docs/plugins/lua.rst

@@ -14,6 +14,39 @@ The Lua 5.1 Reference Manual
 
 .. important:: This section serves as an introduction to the Lua scripting integration in IOLITE. For further details, make sure to check out the :ref:`api_lua` documentation to quickly locate the functionality you are looking for.
 
+Writing your first script in Lua
+--------------------------------
+
+This short tutorial serves as a step-by-step guide to writing your first Lua script in IOLITE.
+
+.. important::
+  This guide requires the latest version of the Lua plugin for IOLITE to be installed. Please check the section :ref:`working_with_plugins` for more details.
+
+Open up your favorite code editor and create a new file. Copy and paste the following Lua script, which logs two strings to the console:
+
+.. code-block:: lua
+
+  Log.load()
+
+  -- Logs each time the script gets (re-)loaded
+  Log.log_info("Hello world! Script loaded!")
+
+  function OnActivate(entity)
+    -- Logs once the component becomes active
+    Log.log_info("Hello world! Component active!")
+  end
+
+After that, continue with the following steps:
+
+1. Store the script in ``default/media/scripts/`` and name it ``hello_world.lua``
+2. Open up IOLITE, ensure that the editor is active, and head over to the *World Inspector*
+3. Create a new entity with a script component attached to it
+4. In the property inspector, set the ``Script`` property to ``hello_world`` (without the extension)
+5. Switch to the game mode by clicking ``[Game Mode]`` in the menu bar
+6. Press ``[F2]`` to open up the console and check if the strings have been logged successfully
+
+Keep IOLITE open and modify the strings passed to the log functions. Every time you save the script, it triggers a hot reload. Notice how the global log call gets executed while the call in ``OnActivate`` is not. This call can be, e.g., triggered by switching back and forth between the game mode and the editor; the editor can be activated using ``[F3]``.
+
 Lua runtime and libraries
 -------------------------
 

iolite_docs/requirements.txt

@@ -1,4 +1,5 @@
 furo
+sphinx
 sphinxext-opengraph
 sphinx-copybutton
-sphinx-inline-tabs
+sphinx-inline-tabs

iolite_docs/support.rst

@@ -1,5 +1,5 @@
-🚀 Support the development
-===========================
+🚀 Support us 
+=============
 
 If you would like to support the development of IOLITE, please consider `subscribing to IOLITE PRO <https://iolite-engine.com/subscribe>`_. In addition to all the features of the free version, the PRO version supports the following: