diff --git a/docs/advanced/concepts.md b/docs/advanced/concepts.md index b75b5273c..2b8d733d8 100644 --- a/docs/advanced/concepts.md +++ b/docs/advanced/concepts.md @@ -4,6 +4,12 @@ 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. @@ -68,7 +74,7 @@ It is complicated to use them, but in combination with an IDE and a debugger it is very usefull to analyse even complex problems or write new additions to the Moose framework. -# Static loading vs. dynamic loading +# 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 @@ -85,18 +91,98 @@ 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. -The other way on loading scripts is by using `DO SCRIPT`. This time the mission +# 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 usefull for very small -script snippets. But we can use it to load a file from our hard drive like this: +script snippets. But we can use it to load a file from your hard drive like +this: ```lua -aaa +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. +But double square brackets is 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 usefull 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 then `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 usefull for Moose developers and it is a requirement to use a debugger. +This will be explained later in the [Debugger Guide]. + +# Automatic dynamic loading + +```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 MOOSE MISSION SCRIPT FROM HARD DISK *** ' ) + dofile(MissionScript) + do return end + end + end +else + env.error( '*** LOAD MOOSE 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++ -# What is a debugger (good for) + [Git]: https://en.wikipedia.org/wiki/Git [GitHub]: https://github.com/ @@ -110,3 +196,7 @@ aaa [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 diff --git a/docs/advanced/debugger.md b/docs/advanced/debugger.md new file mode 100644 index 000000000..2c43bff06 --- /dev/null +++ b/docs/advanced/debugger.md @@ -0,0 +1,8 @@ +--- +title: Debugger +parent: Advanced +nav_order: 100 +--- + +{: .warning } +> THIS DOCUMENT IS STILL WORK IN PROGRESS!