diff --git a/docs/beginner/hello-world-build.md b/docs/beginner/hello-world-build.md new file mode 100644 index 000000000..fde7e63da --- /dev/null +++ b/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! diff --git a/docs/beginner/hello-world.md b/docs/beginner/hello-world.md new file mode 100644 index 000000000..48f7bcaf4 --- /dev/null +++ b/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`.
+ > So `CONDITIONS` must left blank when using it.
+ > **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.
+> The difference between `Moose_.lua` and `Moose.lua` will be explained later.
+> This doesn't matter at this time. + +{: .important } +> The trigger `4 MISSION START` will be executed **before** the mission is started!
+> 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
+ `1 ONCE (Load Mission Script ...)` + + ![dcs-triggers-once.png](../images/beginner/dcs-triggers-once.png) + +- The configured options will be shown.
+ In the middle part the `CONDITIONS` will be shown.
+ 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).
+> *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 diff --git a/docs/beginner/introduction.md b/docs/beginner/introduction.md new file mode 100644 index 000000000..38e3334cd --- /dev/null +++ b/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 diff --git a/docs/beginner/tipps-and-tricks.md b/docs/beginner/tipps-and-tricks.md index 3fa2d8bc2..3ea1bd781 100644 --- a/docs/beginner/tipps-and-tricks.md +++ b/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/ diff --git a/docs/images/beginner/dcs-menu-mission.png b/docs/images/beginner/dcs-menu-mission.png new file mode 100644 index 000000000..0c69f781a Binary files /dev/null and b/docs/images/beginner/dcs-menu-mission.png differ diff --git a/docs/images/beginner/dcs-message.jpg b/docs/images/beginner/dcs-message.jpg new file mode 100644 index 000000000..e07a88fdb Binary files /dev/null and b/docs/images/beginner/dcs-message.jpg differ diff --git a/docs/images/beginner/dcs-my-missions.png b/docs/images/beginner/dcs-my-missions.png new file mode 100644 index 000000000..f99f9ccd0 Binary files /dev/null and b/docs/images/beginner/dcs-my-missions.png differ diff --git a/docs/images/beginner/dcs-triggers-mission-start-actions-conf.png b/docs/images/beginner/dcs-triggers-mission-start-actions-conf.png new file mode 100644 index 000000000..b205bdf2e Binary files /dev/null and b/docs/images/beginner/dcs-triggers-mission-start-actions-conf.png differ diff --git a/docs/images/beginner/dcs-triggers-mission-start-actions.png b/docs/images/beginner/dcs-triggers-mission-start-actions.png new file mode 100644 index 000000000..06ed821fc Binary files /dev/null and b/docs/images/beginner/dcs-triggers-mission-start-actions.png differ diff --git a/docs/images/beginner/dcs-triggers-mission-start-conditions.png b/docs/images/beginner/dcs-triggers-mission-start-conditions.png new file mode 100644 index 000000000..d051b07cd Binary files /dev/null and b/docs/images/beginner/dcs-triggers-mission-start-conditions.png differ diff --git a/docs/images/beginner/dcs-triggers-mission-start-conf.png b/docs/images/beginner/dcs-triggers-mission-start-conf.png new file mode 100644 index 000000000..67d323e77 Binary files /dev/null and b/docs/images/beginner/dcs-triggers-mission-start-conf.png differ diff --git a/docs/images/beginner/dcs-triggers-mission-start.png b/docs/images/beginner/dcs-triggers-mission-start.png new file mode 100644 index 000000000..60b0bef27 Binary files /dev/null and b/docs/images/beginner/dcs-triggers-mission-start.png differ diff --git a/docs/images/beginner/dcs-triggers-once-actions.png b/docs/images/beginner/dcs-triggers-once-actions.png new file mode 100644 index 000000000..b93b1a65b Binary files /dev/null and b/docs/images/beginner/dcs-triggers-once-actions.png differ diff --git a/docs/images/beginner/dcs-triggers-once-conditions.png b/docs/images/beginner/dcs-triggers-once-conditions.png new file mode 100644 index 000000000..7bc4799a7 Binary files /dev/null and b/docs/images/beginner/dcs-triggers-once-conditions.png differ diff --git a/docs/images/beginner/dcs-triggers-once-conf.png b/docs/images/beginner/dcs-triggers-once-conf.png new file mode 100644 index 000000000..fd45b5761 Binary files /dev/null and b/docs/images/beginner/dcs-triggers-once-conf.png differ diff --git a/docs/images/beginner/dcs-triggers-once.png b/docs/images/beginner/dcs-triggers-once.png new file mode 100644 index 000000000..b15125839 Binary files /dev/null and b/docs/images/beginner/dcs-triggers-once.png differ diff --git a/docs/images/beginner/dcs-triggers-toolbar.png b/docs/images/beginner/dcs-triggers-toolbar.png new file mode 100644 index 000000000..08af0b49f Binary files /dev/null and b/docs/images/beginner/dcs-triggers-toolbar.png differ