weyne/DCS_mission_creating
1
0
Fork 0
mirror of https://github.com/weyne85/DCS_mission_creating.git synced 2025-08-15 13:17:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
weyne
2024-05-14 19:54:32 +02:00
commit 38cff47ee6
1184 changed files with 531113 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
MOOSE/docs/advanced/concepts.md Normal file
View File

@@ -0,0 +1,263 @@
---
title: Concepts
parent: Advanced
nav_order: 01
---
# Concepts
{: .no_toc }
1. Table of contents
{:toc}
If you want to get deeper into Moose, you will encounter a few terms and
concepts that we will explain here. You will need them for the later pages.
# Git and GitHub
Moose has about 260.000 lines of code and the amount is increasing each week.
To maintain such a big code base a vcs (version control system) is needed.
Moose uses [GitHub] as developer platform to create, store, and manage the code.
[GitHub] uses [Git] as version control system and provides additional
functionality like access control, bug tracking, feature requests and much more.
As a Moose user you don't need to learn how to use [Git]. You can download the
files on [GitHub] with a browser. But using [Git] will ease up the steps to keep
the Moose version on your hard disk up to date.
You will need to interact with [GitHub]. At least to download the Moose files.
For non-developers the page can be confusing. Take your time and read this
documentation. We are not able to explain every single detail on using [GitHub]
and [Git]. Especially because it is changing really quick and this documentation
will not. So try to use the help system of [GitHub] or find some videos on
[YouTube]. If you get stuck ask for help in the [Moose Discord].
Moose uses more than one repository on [GitHub] which doesn't exactly make it
any clearer. A list can be found on the [reposities] page.
# Branches: master & develop
As already explained in the [overview] two branches are used:
- Branch [master]: Stable release branch.
- Branch [develop]: Newest development with more OPS classes.
As a starter it is okay to begin your journey with the `master` branch.
If you are interested in some newer classes you need to use the `develop`
branch. The later one is also very stable, but it's missing more detailed
documentation and example missions for some of the new OPS classes.
You can switch between these branches with a drop down in the upper left corner
of the [GitHub] repository page. The list of branches is long. So it is a best
practice to save a bookmark in your browser with the links above.
Both branches are available on most of the different repositories. But because
of a limitation of [GitHub pages], we had to split the documentation in two
different repositories:
- Documentation of `master` branch: [MOOSE_DOCS]
- Documentation of `develop` branch: [MOOSE_DOCS_DEVELOP]
# Build result vs. source files
Moose consists of more than 140 individual files with the file extension `.lua`.
They are places in a [directory tree], which makes it more organized and its
semantic is pre-defined for [IntelliSense] to work.
On every change which is pushed to [GitHub] a build job will combine all of
these files to a single file called `Moose.lua`. In a second step all
comments will be removed to decrease the file size and the result will be saved
as `Moose_.lua`. These both files are created for users of Moose to include in
your missions.
The individual `.lua` files are used by the Moose developers and power users.
It is complicated to use them, but in combination with an IDE and a debugger it
is very useful to analyze even complex problems or write new additions to the
Moose framework.
# Static loading
If you add a script file with a `DO SCRIPT FILE` trigger, like we described in
[Create your own Hello world], the script file will be copied into the mission
file. This mission file (file extension .MIZ) is only a compressed ZIP archive
with another file ending.
If you change the script file after adding it to the mission, the changes are
not available on mission start. You have to re-add the script after each change.
This can be very annoying and often leads to forgetting to add the change again.
Then you wonder why the mission does not deliver the desired result.
But when the mission is finished you can upload it to your dedicated DCS server
or give it to a friend and it should run without problems. This way of embedding
the scripts do we call `static loading` and the resulting mission is very
portable.
# Dynamic loading of mission scripts
The other way of loading scripts is by using `DO SCRIPT`. This time the mission
editor don't show a file browse button. Instead you see a (very small) text
field to enter the code directly into it. It is only useful for very small
script snippets. But we can use it to load a file from your hard drive like
this:
```lua
dofile('C:/MyScripts/hello-world.lua')
dofile('C:\\MyScripts\\hello-world.lua')
dofile([[C:\MyScripts\hello-world.lua]])
```
So all lines above do the same. In [Lua] you need to specify the path with
slashes, escape backslashes or use double square brackets around the string.
Double square brackets are usefull, because you can copy paste the path
without any modification.
If you upload a mission with this code, you need to create the folder
`C:\MyScripts\` on the server file system and upload the newest version of
`hello-world.lua`, too. The same applies, if you give the mission to a friend.
This makes the mission less portable, but on the other hand the mission uses the
file on the hard disk, without the need to add it to the mission again.
All you need to do is save the file and restart the mission.
The following can be used to increase portability:
```lua
dofile(lfs.writedir() .. '/Missions/hello-world.lua')
```
The function `lfs.writedir()` will return your [Saved Games folder].
So you place the scripts in the subfolder Missions. This way the folder
structure is already available on all target systems. But you need to ensure
mission and script are both in sync to avoid problems. If you changed both and
upload only one of them to your server, you may get trouble.
There is another method you may find useful to dynamically load scripts:
```lua
assert(loadfile('C:/MyScripts/hello-world.lua'))()
assert(loadfile('C:\\MyScripts\\hello-world.lua'))()
assert(loadfile([[C:\MyScripts\hello-world.lua]]))()
```
It is a little bit harder to read and write because of all these different
brackets. Especially the one on line 3. But it is a little safer than `dofile`.
Because of readability I prefer to use `dofile`.
# Dynamic loading of Moose
Of course you can use the same method to load Moose. This way you can place one
Moose file in your [Saved Games folder], which is used by multiple missions.
If you want to update Moose you just need to replace the file and all missions
will use the new version. But I prefer to add Moose by a `DO SCRIPT FILE`
trigger so I can add and test the new version for each mission step by step.
But we added two different ways to load the Moose source files automatically.
This is useful for Moose developers and it is a requirement to use a debugger.
This will be explained later in the [Debugger Guide].
# Automatic dynamic loading
With the code below you can have the advantages of both approaches.
- Copy the code into your mission script at the beginning.
- Save the mission script into the folder Missions in your [Saved Games folder].
- Change script filename in line 2 to match to your script.
- [De-Sanitize] your `MissionScripting.lua`.
Now the mission will use the script on your hard drive instead of the script
embedded in th MIZ file, as long as it is available. So you can chnge the
script, save it and restart the mission, without the need to readd it after each
change.
If you reach a stable state in your script development and want to upload the
mission to your server or give it to a friend, then just add the script again
like in the static method and save the mission.
{: .important }
> Do not forget to readd the script, prior uploading or sharing the mission,
> or it will run with an outdated version of your script and may fail if the
> objects in the mission don't match to this old version.
```lua
-- Use script file from hard disk instead of the one included in the .miz file
if lfs and io then
MissionScript = lfs.writedir() .. '/Missions/hello-world-autodyn.lua'
-- Check if the running skript is from temp directory to avoid an endless loop
if string.find( debug.getinfo(1).source, lfs.tempdir() ) then
local f=io.open(MissionScript,"r")
if f~=nil then
io.close(f)
env.info( '*** LOAD MISSION SCRIPT FROM HARD DISK *** ' )
dofile(MissionScript)
do return end
end
end
else
env.error( '*** LOAD MISSION SCRIPT FROM HARD DISK FAILED (Desanitize lfs and io)*** ' )
end
--
-- Simple example mission to show the very basics of MOOSE
--
MESSAGE:New( "Hello World! This messages is printed by MOOSE!", 35, "INFO" ):ToAll():ToLog()
```
# IDE vs. Notepad++
As a beginner you should start with a good text editor, which supports syntax
highlighting of [Lua] code. This must not be [Notepad++]. It can be any other
powerful editor of your choice. Do yourself a favor and don't use the Windows
editor.
If you are a developer of [Lua] or another programming language, then your are
most likely familiar with an IDE (Integrated Develop Environment).
Otherwise you should know, that an IDE may help you with code completion,
Refactoring, Autocorrection, Formatting Source Code, showing documentation
as popup on mouse hover over keywords and Debugging.
There are different IDEs available. And not all IDEs support all features.
The three most important for Moose are:
- [Eclipse LDT]
- [Visual Studio Code]
- [PyCharm] (or [IntelliJ IDEA])
Eclipse has the best support for hover documentation and [IntelliSense] with
Moose. The Inventor of Moose (FlightControl) did an amazing job by adding an
integration to Eclipse LDT (a special version for Lua).
Unfortunately Eclipse LDT is not maintained any longer (last release 2018).
And the debugger doesn't work anymore, since an update of DCS.
In Visual Studio Code the support of Lua can be added by an addon.
The debugger works with Moose and DCS, but showing the LuaDoc and [IntelliSense]
is very limited.
PyCharm supports Lua also with an addon. The debugger works with Moose and DCS,
but showing the LuaDoc and [IntelliSense] is very limited.
It is up to you to choose the IDE according to your taste. Guides on how to
setup Moose with different IDEs and Debuggers are provided later in this
documentation.
[Git]: https://en.wikipedia.org/wiki/Git
[GitHub]: https://github.com/
[YouTube]: https://www.youtube.com/
[Moose Discord]: https://discord.gg/gj68fm969S
[overview]: ../index.md
[reposities]: ../repositories.md
[master]: https://github.com/FlightControl-Master/MOOSE/tree/master
[develop]: https://github.com/FlightControl-Master/MOOSE/tree/develop
[GitHub pages]: https://pages.github.com/
[MOOSE_DOCS]: https://flightcontrol-master.github.io/MOOSE_DOCS/
[MOOSE_DOCS_DEVELOP]: https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/
[directory tree]: https://github.com/FlightControl-Master/MOOSE/tree/master/Moose%20Development/Moose
[Saved Games folder]: ../beginner/tipps-and-tricks.md#find-the-saved-games-folder
[Lua]: https://www.lua.org/
[Create your own Hello world]: ../beginner/hello-world-build.md
[Debugger Guide]: debugger.md
[IntelliSense]: https://en.wikipedia.org/wiki/IntelliSense
[De-Sanitize]: desanitize-dcs.md
[Notepad++]: https://notepad-plus-plus.org/downloads/
[Eclipse LDT]: https://projects.eclipse.org/projects/tools.ldt
[Visual Studio Code]: https://code.visualstudio.com/
[PyCharm]: https://www.jetbrains.com/pycharm/
[IntelliJ IDEA]: https://www.jetbrains.com/idea/

8
MOOSE/docs/advanced/debugger.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: Debugger
parent: Advanced
nav_order: 100
---
{: .warning }
> THIS DOCUMENT IS STILL WORK IN PROGRESS!

93
MOOSE/docs/advanced/desanitize-dcs.md Normal file
View File

@@ -0,0 +1,93 @@
---
title: De-Sanitize DCS
parent: Advanced
nav_order: 98
---
# De-Sanitize the DCS scripting environment
{: .no_toc }
1. Table of contents
{:toc}
De-Sanitize is the a modification performed by the user which disables some
security features of DCS. Without de-sanitizing not all functions of Moose
are available. Let's take a closer look and explain the details:
- In the File-Explorer, navigate to your DCS main [installation folder].
- Navigate to the folder `Scripts` and open the file `MissionScripting.lua` with
a good editor like [Notepad++]{:target="_blank"}.
The original file should look like this:
```lua
--Initialization script for the Mission lua Environment (SSE)
dofile('Scripts/ScriptingSystem.lua')
-- Sanitize Mission Scripting environment
-- This makes unavailable some unsecure functions.
-- Mission downloaded from server to client may contain potentialy harmful lua code
-- that may use these functions.
-- You can remove the code below and make availble these functions at your own risk.
local function sanitizeModule(name)
_G[name] = nil
package.loaded[name] = nil
end
do
sanitizeModule('os')
sanitizeModule('io')
sanitizeModule('lfs')
_G['require'] = nil
_G['loadlib'] = nil
_G['package'] = nil
end
```
In line 17, 18 and 19 the method `sanitizeModule` disables the modules `os`, `io` and `lfs`.
{: .warning }
> This is a security feature to avoid harmfull actions to be executed from
> inside a mission.
>
> ***Disable this on your own risk!***
If the lines will be disabled the lua code inside of missions can use the
following functionality again:
- `os` (at line 17):
- Execution of commands from the operation system is allowed again.
This is needed by some Classes when using [Text-To-Speech] with [SRS]{:target="_blank"}.
But in theory it can also run harmful commands.
- `io` and `lfs` (at line 18 & 19):
- Different libraries to access files on your hard disk or do other io
operations. This is needed by some clases if you want to save and/or
read data. Like persistance for CSAR.
But it may be abused to access or modify sensitive files owned by the user.
If you put two dashes (`--`) in front of each of the lines 17 - 19 the
protection is disabled and the lower part of the file should look this:
```lua
do
--sanitizeModule('os')
--sanitizeModule('io')
--sanitizeModule('lfs')
_G['require'] = nil
_G['loadlib'] = nil
_G['package'] = nil
end
```
Save the file and it will enable the DCS Lua sandbox to access stuff on your computer.
{: .note }
> After each update of DCS you need to repeat this because each update will
> overwrite this file by default.
[installation folder]: ../beginner/tipps-and-tricks.md#find-the-installation-folder-of-dcs
[Notepad++]: https://notepad-plus-plus.org/downloads/
[Text-To-Speech]: text-to-speech.md
[SRS]: https://github.com/ciribob/DCS-SimpleRadioStandalone/releases/latest

84
MOOSE/docs/advanced/eclipse-installation.md Normal file
View File

@@ -0,0 +1,84 @@
---
parent: Advanced
nav_order: 97
---
# Eclipse Installation
{: .no_toc }
1. Table of contents
{:toc}
This guide describes how to install [Eclipse] and install the necessary [Lua]
environment.
{: .note }
> Note that the [Lua] environment is not actively supported any more
> by Oracle. Especially the LDT plugin is not working when installed from the
> market place. The problem and solution is nicely described [in this topic].
## Prerequisites
* Download Eclipse from [eclipse.org].
* Download [dltk-core].
* Download or clone [MOOSE repository] (select branch you want `master` or `develop`).
## Install Eclipse
First you need to install [Eclipse]. It will ask you what kind of environment
you use, *e.g.* C++ or Java or something else. This does not really matter since
we want to use it for Lua and need to install the plugin for [Lua] later.
## Install dltk-core
Before you can install the LDT plugin, you first need to add dltk-core zip file
to the available software sites. Open eclipse, go to the help menu and follow
the steps in the image:
![eclipse-install-ldk-1](../images/install/eclipse/ldk-1.png)
This should then be in the available software sites.
![eclipse-install-ldk-2](../images/install/eclipse/ldk-2.png)
## Install LDT Plugin
Open eclipse and from the "Help" menu open the "Eclipse Marketplase":
![Eclipse-Install_Lua_1](../images/install/eclipse/lua-1.png)
In the "Search" tab find "lua" and install the "Lua Development Tools 1.4.x":
![Eclipse-Install_Lua_2](../images/install/eclipse/lua-2.png)
## Setup Lua Project for MOOSE
Now that Eclipse and LDT are installed, we need to add MOOSE as a LUA project.
Open Eclipse and from the "File" menu select "Other":
![Eclipse-Lua_Project_1](../images/install/eclipse/project-1.png)
In the wizard window that opens select "Lua Project":
![Eclipse-Lua_Project_2](../images/install/eclipse/project-2.png)
Setup the Lua project as described in the image. You need to specify the path to
where you downloaded the MOOSE repository:
![Eclipse-Lua_Project_3a](../images/install/eclipse/project-3.png)
From the "Project" tab select "Properties" and add `Moose/Moose Development/Moose`
to the build path as shown below:
![Eclipse-Lua_Project_4](../images/install/eclipse/project-4.png)
## Finally
Now you are done!
Check that your script explorer looks like in the image below and that the
intellisense is working when you open a MOOSE file:
![Eclipse-Lua_Project_5](../images/install/eclipse/project-5.png)
[Eclipse]: https://www.eclipse.org
[Lua]: https://www.lua.org/
[eclipse.org]: https://www.eclipse.org/downloads/
[dltk-core]: https://www.eclipse.org/downloads/download.php?file=/technology/dltk/downloads/drops/R5.7/R-5.7.1-201703020501/dltk-core-R-5.7.1-201703020501.zip
[MOOSE repository]: https://github.com/FlightControl-Master/MOOSE/
[in this topic]: https://www.eclipse.org/forums/index.php/t/1101907/

20
MOOSE/docs/advanced/index.md Normal file
View File

@@ -0,0 +1,20 @@
---
has_children: true
nav_order: 3
---
# Advanced
In this section we will add the documentation for all subjects that go beyond
the beginner topics, but which are interesting for mission builders or power
users.
{: .note }
> This documentation is WIP (work in progress) and it will take some time to
> fill it with usefull and up to date informations. Please be patient and check
> back here from time to time to see if there is anything new for you.
If you cannot find the information you are looking for here in the new
documentation, please take a look at the [archive].
[archive]: ../archive/index.md

159
MOOSE/docs/advanced/text-to-speech.md Normal file
View File

@@ -0,0 +1,159 @@
---
parent: Advanced
nav_order: 99
---
# Text to Speech
{: .no_toc }
1. Table of contents
{:toc}
This guide describes how to configure and use [Text-To-Speech{:target="_blank"}
(or TTS) with MOOSE. We use [DCS Simple Radio Standalone] (DCS-SRS) to generate
the audio and send it to the client. SRS is a well known VOIP client simulating
a radio in DCS.
{: .note }
> Only clients which uses SRS are able to hear the generated radio calls.
> This is not compatible with the in game VOIP audio system from Eagle Dynamics!
## Prerequisites
- Download and install [DCS Simple Radio Standalone]{:target="_blank"} (DCS-SRS).
- Use a good text editor like [Notepad++]{:target="_blank"}.
- Create a simple test mission with Moose included and a "... from parking hot"
airplane or helicopter.
- [De-Sanitize the DCS scripting environment].
## Start SR-Server and connect the client
- Navigate to the install directory of SRS.
- As default it should be located here: `C:\Program Files\DCS-SimpleRadio-Standalone`
- We are interested in the executable files:
![srs-executables](../images/install/text-to-speech/srs-executables.png)
- Start the server by double click on `SR-Server.exe`.<br />
It should looks like this:
![srs-server](../images/install/text-to-speech/srs-server.png)
- Start the `SR-ClientRadio.exe`.
- Connect to the local server:
- Use the port shown in the server window (default is 5002).
- Use the ip of the windows loopback device (which is 127.0.0.1).
- Example: `127.0.0.1:5002`
![srs-client](../images/install/text-to-speech/srs-client.png)
- If asked if you want to allow changes to your PC, say yes.
- After you clicked on Connect and some seconds the status should look like this:
![srs-status-1](../images/install/text-to-speech/srs-status-1.png)
- Your server UI now shows 1 connected client.
- Click on „toggle radio overlay“ on the client. A small grey window will pop-up.
## Start DCS World and your test mission
- Jump into a plane or helicopter.
- The connection status on the client UI and overlay should be changing
and shows the available radios of the module and it's frequencies:
![srs-overlay](../images/install/text-to-speech/srs-overlay.png)
- The third green connector on the client UI should be green now:
![srs-status-2](../images/install/text-to-speech/srs-status-2.png)
## Command line test with Power Shell
- Use the search icon in windows to locate and start `PowerShell`, you’ll get a
blue terminal window:
![powershell-1](../images/install/text-to-speech/powershell-1.png)
- Now navigate in PowerShell to the SRS install folderwith the following command:
`cd 'C:\Program Files\DCS-SimpleRadio-Standalone\'`
{: .note }
> Change the path if you choose another installation directory for SRS.
- Type `dir` and press enter to get a listing of all files in the directory.
- `DCS-SR-ExternalAudio.exe` should be amongst them.
![powershell-2](../images/install/text-to-speech/powershell-2.png)
- Now we are going to create a text-to-speech command which should be sent to
the radio on your airplane or helicopter.
- The parameter `-t` will define the text to send.
- The frequency will be defined with `-f`. Adopt it to match the frequency of
your airplane or helicopter! For example 251.
- And the modulation is set by `-m`. For example AM.
- Define the coalition with `-c`. 0 is Spectator, 1 is Red, 2 is Blue.
`.\DCS-SR-ExternalAudio.exe -t "Hello Moosers" -f 251 -m AM -c 2`
- The console output should look like this:
![powershell-3](../images/install/text-to-speech/powershell-3.png)
**If you can hear the voice on the cockpit radio, you are done!**
If you get UpnP/Network errors, you need to allow DCS-SR-ExternalAudio.exe to
traverse your firewall.
{: .note }
> You can raun `DCS-SR-ExternalAudio.exe` without any parameters to get help.
## Firewall Setup
- On Windows search, type Firewall and open „Firewall- and Network Protection“.
Click on „Extended Setting“ (you need admin rights to do that).
- You will need two incoming and two outgoing rules (4 overall), right-click on
incoming/outgoing rules to create new rules.
- Give the rule a nice name:
- Protocols and Services – you need to create ONE rule for TCP and another one
for UDP. Select TCP from the drop down:
- On Programs and Services, enable 'this program' and use search to locate and
select DCS-SR-ExternalAudio.exe:
- Click „ok“ to save and close the rule.
- Repeat for UDP.
- Repeat twice for outgoing, one for TCP and one for UDP.
- You’re done and can return to 'Command line test'.
## Google TTS
- For Google TTS you need to have a Google Cloud Account (a testing one will do).
- You can start here: <https://cloud.google.com/text-to-speech/>
- You need to create a projekt and enable the 'Cloud Text-To-Speech API' in it.
- You also need to create a service-account and create a `.json` key file for it.
There’s a lot of supporting information on the Google Cloud Site to help you
with that. Similar to 'Command line test', you can test your setup on the
command line. Here is an example that assumed your .json key file resides in the
SRS directory:
`.\DCS-SR-ExternalAudio.exe -t "Hello Moosers" -f 251 -m AM -c 2 -z -G .\yourgoogleaccount.json`
[Text-To-Speech]: https://en.wikipedia.org/wiki/Speech_synthesis
[DCS Simple Radio Standalone]: https://github.com/ciribob/DCS-SimpleRadioStandalone/releases/latest
[De-Sanitize the DCS scripting environment]: desanitize-dcs.md
[Notepad++]: https://notepad-plus-plus.org/downloads/