Merge branch 'userguide'

docs/beginner/hello-world-build.md

@@ -0,0 +1,9 @@
+---
+parent: Beginner
+nav_order: 03
+---
+
+# Create your own Hello world
+
+{: .warning }
+> THIS DOCUMENT IS STILL WORK IN PROGRESS!

docs/beginner/hello-world.md

@@ -0,0 +1,178 @@
+---
+parent: Beginner
+nav_order: 02
+---
+
+# Hello world mission
+{: .no_toc }
+
+1. Table of contents
+{:toc}
+
+## Let's see MOOSE in action
+
+It is tradition that the first piece of code is a very simple example on showing
+a "Hello world!" to the user. We have prepared this example mission for you. So
+you can download and run it. Later on we will analyze it to explain the basics
+on how to add MOOSE to your own missions.
+
+- Download the demo mission [001-hello-world.miz] by clicking on the link.
+- Put the .miz file into your Missions subfolder of your [Saved Games folder].
+- Start DCS, choose `MISSION` in the menu on the right side:
+
+    ![dcs-menu-mission.png](../images/beginner/dcs-menu-mission.png)
+
+- Click on `My Missions`, choose the `hello-world` mission and click on `OK`.
+
+    ![dcs-my-missions.png](../images/beginner/dcs-my-missions.png)
+
+- It is an empty mission, so skip `BRIEFING` with `START` and then `FLY`.
+- You spawn as a spectator. After some seconds you will see this message in
+  the upper right corner:
+
+    ![dcs-message.jpg](../images/beginner/dcs-message.jpg)
+
+Ok, that's all. There is nothing more to see in this mission. This is not
+particularly impressive and can also be achieved using standard Lua in DCS
+(i.e. without MOOSE), but we want to keep it simple at the beginning.
+
+{: .note }
+> If the text don't show up, the mission might be corrupted. Please contact the
+> team on Discord for futher instructions.
+
+## Let's take a look under the hood
+
+- Go back to the main window and open the `MISSION EDITOR`.
+- Choose `open mission` navigate to `My Missions` and open 001-hello-world.miz.
+- On the left side activate `TRIGGERS`:
+
+    ![dcs-triggers-toolbar.png](../images/beginner/dcs-triggers-toolbar.png)
+
+- On the right side the `TRIGGERS` dialog opens with a lot of options.
+- First take a look at the available triggers:
+
+    ![dcs-triggers-mission-start.png](../images/beginner/dcs-triggers-mission-start.png)
+
+- You will see two:
+  - One in yellow with type `4 MISSION START` and name `Load MOOSE` and
+  - one in green with type `1 ONCE` and name `Load Mission Script`.
+
+### Execution of Moose
+
+- Click on the yellow one to show all of it options.
+
+- In the middle part the `CONDITIONS` will be shown.
+  For this trigger there are no conditions configured.
+
+    ![dcs-triggers-mission-start-conditions.png](../images/beginner/dcs-triggers-mission-start-conditions.png)
+
+    {: .important }
+    > The trigger type `4 MISSION START` does not support `CONDITIONS`. <br />
+    > So `CONDITIONS` must left blank when using it. <br />
+    > **If you add a condition the trigger will never be executed!**
+
+- On the right side the `ACTIONS` will be shown:
+
+    ![dcs-triggers-mission-start-actions.png](../images/beginner/dcs-triggers-mission-start-actions.png)
+
+- A `DO SCRIPT FILE` is configured, which executes the file `Moose_.lua`
+
+{: .highlight }
+> This is the execution of the Moose framework included in the mission as one single file. <br />
+> The difference between `Moose_.lua` and `Moose.lua` will be explained later. <br />
+> This doesn't matter at this time.
+
+{: .important }
+> The trigger `4 MISSION START` will be executed **before** the mission is started! <br />
+> This is important, because Moose **must** be executed before other scripts, that want to use Moose!
+
+### Execution of the mission script
+
+- Now move back to the left `TRIGGERS` area and click on the green trigger <br />
+  `1 ONCE (Load Mission Script ...)`
+
+    ![dcs-triggers-once.png](../images/beginner/dcs-triggers-once.png)
+
+- The configured options will be shown. <br />
+  In the middle part the `CONDITIONS` will be shown. <br />
+  For this trigger there is one condition configured:
+
+    ![dcs-triggers-once-conditions.png](../images/beginner/dcs-triggers-once-conditions.png)
+
+- The combination of `1 ONCE` with `TIME MORE(1)` will ensure, that the mission
+  script is executed 1 second after the mission is started.
+
+- On the right side the `ACTIONS` will be shown:
+
+    ![dcs-triggers-once-actions.png](../images/beginner/dcs-triggers-once-actions.png)
+
+- A `DO SCRIPT FILE` is configured, which executes the file `001-hello-world.lua`.
+
+{: .highlight }
+> This is the execution of the mission script, which you will create in the future.
+
+{: .important }
+> Most important is the fact, that the mission script (`001-hello-world.lua`)
+> is executed **after** `Moose_.lua`, because the mission script needs the
+> classes defined in `Moose_.lua`. And they are only available when `Moose_.lua`
+> is executed before the mission script.
+
+### Inspect the code of the mission script
+
+The file `001-hello-world.lua` consists of following code:
+
+```lua
+--
+-- Simple example mission to show the very basics of MOOSE
+--
+MESSAGE:New( "Hello World! This messages is printed by MOOSE", 35, "INFO" ):ToAll()
+```
+
+- The first three lines starting with `--` are comments and will be ignored.
+
+- Line 4 is the one with the "magic":
+
+  - With `MESSAGE` we use the class [Core.Message].
+  
+The part before the dot (Core) is the section where the class is placed.
+It is important for the Moose programmes to have a structure where the classes
+are placed. But in the code itself it is not used.
+
+#### What is a class?
+
+{: .highlight }
+> In object-oriented programming, a class is an extensible program-code-template
+> for creating objects, providing initial values for state (member variables)
+> and implementations of behavior (member functions or methods). <br />
+> *Source [Wikipedia:Class]{:target="_blank"}*
+
+After the class name we call a method of that class. We do this with semicolon
+followed by the name of the method and a pair of round brackets.
+Here we call the method `New`, which creates a new MESSAGE object.
+
+We give it three parameters within the round brackets, which are divided by commas:
+1. The text we want to show: `"Hello World! ..."`
+1. The time in seconds the messages should be visible: `35`
+1. And the type of message: `"INFO"`
+
+- With `New` the MESSAGE object is created, but the message is still not printed
+  to the screen.
+- This is done by `:ToAll()`. Another method of [Core.Message] which sends the
+  message to all players, no matter if they belong to the RED or BLUE coalition.
+
+If you you want to read more about [Core.Message] click on the link.
+The page with all the Methods and Fields is very long and this might be
+daunting, but for the copy and paste approach, you won't need it often.
+
+And if you want to learn how to use more of that stuff, you will become
+compftable in filtering these informations fast.
+
+## Next step
+
+Now it is time to [create your own Hello world] mission.
+
+[Saved Games folder]: ../beginner/tipps-and-tricks.md#find-the-saved-games-folder
+[hello-world demo mission]: https://raw.githubusercontent.com/FlightControl-Master/MOOSE_MISSIONS/master/Core/Message/001-hello-world.miz
+[Core.Message]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/Documentation/Core.Message.html
+[Wikipedia:Class]: https://en.wikipedia.org/wiki/Class_(computer_programming)
+[create your own Hello world]: hello-world-build.md

docs/beginner/introduction.md

@@ -0,0 +1,106 @@
+---
+parent: Beginner
+nav_order: 01
+---
+# Introduction
+{: .no_toc }
+
+1. Table of contents
+{:toc}
+
+This very short chapter is for people identifying as a consumer of MOOSE and not
+wishing to learn to script. This is a condensed FAQ and set of links to get you
+up and running. It specifically avoids any complexity.
+
+## What is MOOSE?
+
+[DCS] has included a [Simulator Scripting Engine] (short SSE). This SSE gives
+mission designers access to objects in the game using [Lua] scripts.
+
+**M**ission **O**bject **O**riented **S**cripting **E**nvironment, is a
+scripting framework written in [Lua] that attempts to make the scripting of
+missions within DCS easier, simpler and shorter than with the standard methods.
+
+MOOSE is over 5 MB of code, with as many words as the Bible and the core of it
+was written over several years by one person.
+
+MOOSE is the brain-child of an talented programmer with the alias FlightControl.
+If you want to know more about this topic, check out FC’s [MOOSE for Dummies]
+videos on YouTube.
+
+{: .note }
+> We recommend video playback at 1.5x speed, as FC speaks slowly and distinctly.
+
+## What is Lua?
+
+[Lua] is a lightweight, programming language designed primarily to be embedded
+in applications. It's main advantages are:
+
+- It is fast,
+- it is portabel (Windows, Linux, MacOS),
+- it is easy to use.
+
+[Lua] is embedded in DCS, so we can use it without any modifacation to the game.
+
+## What is are scripts, frameworks and classes?
+
+A script is a set of instructions in plain text read by a computer and processed
+on the fly. Scripts do not need to be compiled before execution, unlike exe
+files.
+
+A framework is a structure that you can build software (or in this case missions)
+on. It serves as a foundation, so you're not starting entirely from scratch.
+It takes a lot of work off your hands because someone else has thought about it
+and provides ready-made building blocks for many situations.
+
+These building blocks are called classes in object oriented programming.
+
+## What can MOOSE do for me?
+
+Whilst MOOSE can be used to write customised [Lua] scripts, you are probably not
+caring for learning [Lua] right now. Instead you can use a MOOSE script written
+by someone else by just copy and paste it. You can configure the basic settings
+of the classes to fit your needs in your mission.
+
+Here are a few suggestions for well-known and popular classes:
+
+- [Ops.Airboss] manages recoveries of human pilots and AI aircraft on aircraft
+  carriers.
+- [Functional.RAT] creates random airtraffic in your missions.
+- [Functional.Range] (which counts hits on targets so you can practice),
+- [Functional.Fox] to practice to evade missiles without being destroyed.
+- and many more!
+
+You will need to look through examples to know what functionallity you want to
+add to your missions.
+
+## What if I don’t want to learn scripting?
+
+The good news for you: You don't need to become a professional [Lua] programmer
+to use MOOSE. As explained already, you can copy and paste the code from example
+missions. You need some basics how to add triggers in the mission editor. But we
+will cover this later.
+
+If you want to modify the behaviour of the classes slightly, some basics about
+the [Lua] synthax (the rules how to write the code) will help you to avoid
+errors.
+
+The more customizations you want to make, the more knowledge about [Lua] you
+will need. But you can learn this step by step.
+
+## Next step
+
+We will start with a very simple demonstartion of MOOSE in the next section
+[Hello world mission].
+
+[DCS]: https://www.digitalcombatsimulator.com/en/
+[Simulator Scripting Engine]: https://wiki.hoggitworld.com/view/Simulator_Scripting_Engine_Documentation
+[Lua]: https://www.lua.org/
+[MOOSE for Dummies]: https://www.youtube.com/watch?v=ZqvdUFhKX4o&list=PL7ZUrU4zZUl04jBoOSX_rmqE6cArquhM4&index=2&t=618s
+
+[Ops.Airboss]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/Documentation/Ops.Airboss.html
+[Functional.RAT]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/Documentation/Functional.RAT.html
+[Functional.Range]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/Documentation/Functional.Range.html
+[Functional.Fox]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/Documentation/Functional.Fox.html
+
+[Hello world mission]: hello-world.md

docs/beginner/tipps-and-tricks.md

@@ -25,5 +25,30 @@ It depends on the platform and the version you choosed to install:
   - If you changed the installation folder of the Standalone version, right
     click on the game icon, open Properties and click on `Open File Location`.
 
+## Find the Saved Games folder
+
+DCS creates a folder to store all user specific configuration and data.
+This folder can be found in your userprofile as subfolder of `Saved Games`.
+
+The easiest way to find it, is to open search and paste the text below into it
+and press Enter:
+
+```%userprofile%\Saved Games```
+
+{: .note }
+> The text will work even if your Windows is installed with another language,
+> e.g. German. This is really usefull.
+
+Depending on the DCS version you will find one of the following folders:
+
+- DCS
+- DCS.openbeta
+
+{: .note }
+> It is good idea to add the folder to the quick access area in the windows
+> explorer. You will use it very often!
+
+For MOOSE users the folders `Missions`, `Logs` and `Config` are most important!
+
 [DCS World Steam Edition]: https://store.steampowered.com/app/223750/DCS_World_Steam_Edition/
 [DCS World Standalone installer]: https://www.digitalcombatsimulator.com/en/downloads/world/