Merge old documentation

.github/workflows/build.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.8 ]
+        python-version: [ 3.11 ]
 
     steps:
     - uses: actions/checkout@master

.wordlist.txt

@@ -1 +1,19 @@
-libre
+libre
+unintuitive
+trainsim
+npc
+thuringia
+maglev
+osm
+png
+GDScript
+Shader
+tscn
+tres
+cfg
+AudioStreamPlayer
+ogg
+LTS
+https
+addon
+addons

README.md

@@ -1,3 +1,20 @@
 # Libre Train Sim documentation
 
 Please note, for the time being there will be a lot of force pushes onto the main branch. We will stop using force pushes as soon as the documentation was completely migrated.
+
+## Language
+
+We try to stick to British English.
+
+1. Use unabigous language.
+2. Be enjoyable to read.
+3. Vvoid personal speech.
+4. A confused reader is bad documentation.
+5. Don't take readers for fools.
+6. Strive to be as accessible as possible while retaining expressiveness.
+
+## Page style
+
+1. Start with a quick abstract what the page is going to teach.
+2. Use tips, notes, warnings, and dangers as required. They catch readers attention.
+3. Document all quirks and name them as such.

docs/contribute/file-structure.md

@@ -0,0 +1,32 @@
+# File Structure
+
+We're moving to a new structure. This process is done one step at a time and not immediate. If you're creating new files, please stick to `underscore_naming`. It prevents accidentally duplicated files.
+
+!!! note "Docs merging note"
+    Copied from the [general information](/manual/editor/03-general-information.md). Not verified.
+
+## File Structure
+- **Blender**: 
+- **Resources**: Here there are all Resources for the track. You could add here your own resources too, but also in a separate unique folder with your Author Name.
+    - **YourTrackName**: In here all special resources for your track are saved. You have to create it.
+        - **Blender**: Here you can store your .blend files. 
+        - **Materials**: Here you can store specific materials for your track. (godot materials)
+        - **Objects**: Here you can store your custom meshes as .obj files.
+        - **RailTypes**: If you want to create own rail types, then here you could save them.
+        - **SignalTypes**: If you want to create own signals, then here you cloud save them.
+        - **Sounds**: Here you can store all sound files, which you need for your track. For example platforms announcments...
+        - **Textures**: In here you can store Images, Textures (.png recommended) which you maybe wanna use in your materials.
+    - (**Basic**: In here many assets are saved which you can use in for your own track. The License of this folder is CC0 (Public Domain)).
+        - ...
+- **Trains**: Here all trains are stored. Every special train his own train folder. Theoretical there some derivates of the train could be stored there too.
+- **Worlds**: Here all Tracks are stored. Per track there should be a unique folder.
+- **addons**: In there is the magic of Libre TrainSim. There are modules like Rails, Signals, but also the addons for Godot saved. **Never change a script or a file in there** 
+
+**What happens if my addon would overwrite an existing file later?**: Your "changed" file won't be effective -> That makes it easier, when a new version of Libre TrainSim comes out, that your content will run too through it.
+
+## File Extensions
+- .gd: Scripts - Written in [GDScript](https://docs.godotengine.org/en/3.5/getting_started/scripting/gdscript/index.html)
+- .tscn: Scenes *(Resouces like a train, a world, or just every other game module in Godot Format)*
+- .tres: Material/Shader/... 
+- .cfg or .save: Configuration Files, which are automaticly generated by the Libre TrainSim tools, they are very important. In it chunks, scenario information and more is stored. 
+

docs/contribute/getting-started.md

@@ -0,0 +1,8 @@
+# Getting started
+
+1. Where to get the source
+2. Fork, Clone, PR Workflow
+3. Code Style
+4. Project Structure
+5. Where to get help
+6. Also welcome artists

docs/contribute/index.md

@@ -0,0 +1,4 @@
+# How to contribute?
+
+!!! note "Missing pages"
+    I'd like to add pages talking about code philosophy, a roadmap, update philosophy, PR workflow, what needs to be done for each release, people we are looking for.

docs/index.md

@@ -8,4 +8,4 @@ We are glad, you have found your way to Libre Train Sim.
 
 ► You want to make your own trains? Our [mod documentation](manual/mods/) holds valuable information for you. This is also a great place for track builders to find information about more sophisticated topics.
 
-► You want to get involved in the development? Being it [translations](contribute/translations.md) or [code contributions](contribute/code/) every support we can get is appreciated.
+► You want to get involved in the development? Being it [translations](contribute/translations.md), [code](contribute/), [art](contribute/), [sound](contribute/), [testing](contribute/) or anything else, every support we can get is appreciated.

docs/manual/editor/00-index.md

@@ -0,0 +1,28 @@
+# Overview
+
+This step-by-step guide aids through the track creation process. If you need help at any point, please head over to [Discord](https://discord.gg/AQdAtZZ) or create a new [issue](https://github.com/Libre-TrainSim/lts-docs/issues/new). There is not a single stupid question. Just unintuitive design and bad documentation.
+
+!!! Note
+
+	This guide originates from the old, 0.8 track creation. In the meantime many things have been improved while others may got worse. We appreciate any feedback we can get.
+
+	In an ideal world, this guide would not be necessary but we are not yet at this point. 
+
+## Tutorial
+
+1. [First steps](01-first-steps.md)
+2. [Getting started](02-getting-started.md)
+3. [Building rails](04-building-rails.md)
+4. [Quick and dirty test setup](05-quick-test-setup.md)
+5. [Station Setup](06-station-setup.md)
+6. [Rail Logic](07-rail-logic.md)
+7. [Adding Landscape Elements](08-adding-landscape.md)
+8.  [Basic World Configuration](09-world-configuration.md)
+9. [Scenario Settings](10-scenario-setup.md)
+10. [NPC Trains](11-npc-trains.md)
+11. [Exporting and Publishing Content](12-export-and-publish.md)
+
+## (Re)moved pages
+
+1. [Importing self-made objects content to Libre TrainSim](../../mods/import-pipeline.md)
+2. [Custom Scripts](../../mods/custom-world-scripts.md)

docs/manual/editor/01-first-steps.md

@@ -0,0 +1,103 @@
+# First steps
+
+## What type of track do I want to do?
+
+Most readers probably already know what they want to build. Sadly, the more important question is if Libre TrainSim can actually handle your track at this stage.
+
+!!! tip "A wholeheartedly advice on scope"
+	You may have heard of term scope, or more precisely over-scope or over-scoping. This is a common pitfall when you start new projects. No one is safe from it. In fact, even settled developers regularly over-scope. Having committed over-scope is nothing you need to be ashamed of! It happens.
+
+	Instead, your main concern *should* be to have something working as fast and small as possible. Either you end up having a somewhat usable and done project, or you have a blast and expand it further. Do yourself the favor and keep this advice close to your heart.
+
+	At the beginning try to limit yourself to two or three stations that work and look great. That feels better than 15 stations that may work as well but don't look, or even worse don't work at all.
+
+### Possible track types
+
+  - Underground tracks
+    - They need to stay underground though
+    - ...or you mix both but crossing the ground results in an ugly transition through the ground.
+  - Suburban/Urban Tacks
+    - The previous documentation bragged that detailed cities are possible...
+    - ... the question is the definition of "detailed".
+
+!!! danger "Theory and practice"
+
+	The bullet points below could very well be possible. **However**, take it with a good portion of salt (a grain of salt is probably not sufficent). **This is case of overselling untested facts.**
+
+	They only remain here as warning for future contributers to manage expectations and to keep some gems of the original documentation.
+
+  - "Simple" tracks, up to 100 km
+    - First, no one ever tested that.
+    - Second, even though the chunk system should be able to handle the size, keep in mind that this size still needs to be filled with content. There is no "Make game button".
+  - Tramways
+    - Could work, sure. But not with cars.
+    - And, you need to make the street models first.
+  - Any kind of freight routes
+    - That is simply not true.
+    - We only support passengers.
+    - You can only drive from one driver's cabin an not switch between multiple.
+    - We bake routes. We don't support switches and back and forth routes.
+    - We don't have cargo trains nor cargo assets.
+  - Hyper loop, mono rails, maglev tracks are possible, too.
+    - You would need to create all required assets.
+    - Nobody ever tested the claim.
+
+### Track design limitations
+
+  1. There is no landscape editor. Landscape is created by placing single objects into the scenery.
+  2. Switching between underground and overground railways will put the ground plane between both parts. This is not a game play relevant issue but surely an artistic one.
+
+## Conception phase
+
+!!! warning
+
+	The following is impossible out of the box and requires a special setup using Godot, mod tools, the editing path put to `res://`, and constant switching between the in-game editor and Godot. To reenable this workflow, there needs to be a special feature devloped.
+
+!!! note "Docs merging note"
+
+	We should probably rewrite all of that. I stopped here. It would be nice to teach some level design practices here. This seems also to be a good point to talk about guidance. (Or rather joke about guidance)
+
+It is highly recommended, that you make yourself a plan how you build your track. *(No shit, Sherlock)*
+We will add a .png file to our floor of our track for orientating where to build tracks later.
+
+### Fictional track
+
+You could make your plan in a graphical Program like Inkscape, or even on a paper. Important is: In the end you will have a .png/jpeg File, which, we could add later to our track.
+
+### Real-world track
+
+You could download Maperative [here](http://maperitive.net/), Unzip it, (on Linux and Mac install Mono before), and start 'Mapertive.exe':
+
+  1. Set to Transport Map: 'Tools' -> 'Add Web Map' -> 'Transport'
+  2. Clear the Web Cache under 'Tools' -> 'Clear Web Tiles Cache'
+  3. Zoom to your area, you want to snapshot
+  4. Set Printing Bounds  under 'Map' -> 'Set Printing Bounds'
+  5. Zoom out with the mouse wheel, and adjust the blue rect to your wanted *(Because our png image could be very large at the end, dont "mess up" the rect with unused space.)*
+  6. For large tracks a scale of 1:64 458 is recommended (Displayed in the bottom left corner) - Just use the Mousewheel for that. Just apply a nearer zoom, if you really need it, or your track is small enough. *(Important: Memorize your applied scale, you will need it later! 
+  7. Now generate the PNG File under 'Tools' -> 'Export to Bitmap' *(That could take up to 30 Minutes at big maps!)*
+  8. In the end you can find your Image in the folder 'output' in the Maperative Directory.
+
+Now we now should have a plan (.png) where to place some rails and where to place houses, Trees, ...
+
+### Downscaled example
+
+!!! note "Docs merging note"
+
+	I would prefer a fictional example without all the noise.
+
+!!! question "Where to put images?"
+
+	We can either store images in a central `img` folder or store them next to the page. Personally, I'd prefer the latter.
+
+![Example Image](01-imgs/map_example.png)
+
+## Height maps
+
+!!! hint
+
+	This is not a exhaustive list. If you feel like something is missing here, please open an [issue](https://github.com/Libre-TrainSim/lts-docs/issues/new).
+
+### Germany
+
+  - [Thuringia](https://de-de.topographic-map.com/maps/64wh/Th%C3%BCringen/)
+  - [Saxony](https://www.geodaten.sachsen.de/digitale-hoehenmodelle-3994.html)

docs/manual/editor/02-getting-started.md

@@ -0,0 +1,89 @@
+# Getting started
+
+## Download and Installation
+
+With the release of v0.9 we migrated to our new in game editor, thus you absolutely need to have the game installed.
+
+## World creation
+
+The editor is split into two parts: There is the world editor used to create the map and the scenario editor for the later scenario creation.
+
+!!! warning "Weird UX"
+    For reasons unknown to mankind the world creation workflow is not straight forward. First, enter the map name in the description then click on new afterwards.
+
+!!! note "Editor data location"
+    The shown file path `user://editor/` is a godot specific file path. The engine takes care of the real location on your machine. Do yourself the favor and stick to the default path. However, if you plan to take advantage of the modding capabilities then a change to `res://mods/` is required.
+
+    Refer to the [modding tutorial](/manual/mods/) for further instructions.
+
+## Camera controls
+
+Our camera operates in two main modes: fly/first-Person mode and orbit mode.
+
+### Fly/First-Person Mode
+
+* Press `RMB` to enter the fly mode.
+* Use `WASDQE` to move the camera.
+* Move the `mouse` to look around.
+* Press `Shift` to move faster.
+* Additionally, the camera automatically accelerates the longer you hold `RMB`.
+
+> I think the mouse wheel did something as well...
+
+### Orbit mode
+
+The orbit mode is the default camera mode and always active.
+
+* Rotate your view using `MMB`.
+* Move on the orbit plane (you want to use that even if you don't know what it means) using `Shift + MMB`.
+* Move on the local plane by pressing `Alt + MMB`.
+* Zoom using the `mouse wheel` or `Ctrl + MMB`.
+
+## Base image
+
+!!! danger "Unsupported feature"
+    This feature is currently not supported in the editor. If you set up the map as a mod, you can add it as a base plane for the chunk following the steps below. This [issue is known and to be fixed](https://github.com/Libre-TrainSim/Libre-TrainSim/issues/399).
+
+!!! note "Docs merging note"
+
+	Only images were copied. No content verification.
+
+Now we need our Track Concept, which we created [here](01-first-steps.md#conception-phase). Open your newly created world, select in the Scene Tab the top node 'World', then click on '+', and search for 'MeshInstance', then click on create. Deactivate the visibilty of the 'Grass' node in the scene tree. its the right icon, which looks like an eye.
+
+![Pic1](02-imgs/CreateNewNodeInWorld.png)
+
+ You could give it a special name if you like by doubleclicking it. Make sure it is selected, and select your Inspector at the right screen.  Select '[empty]' under Mesh, and select 'New QuadMesh'.
+
+![Pic2](02-imgs/GroundAddingPlane.png)
+
+Now it will gonna be a bit complex:
+You need the meter/pixel ratio of your image. If you where using the osm image, you need to count the pixels of the scale bar in your generated png image. You can find the scale bar at the left bottom corner. I count them with gimp: Open the image with gimp, zoom to the left bottom corner, press 'shift m' and drag the tool along the scale bar. In my case I counted 97 Pixels. Above the scale bar there is standing 50m. So my meter/pixel ratio is 50/97.
+Also get the size in pixels of your ground.png file you can find it in gimp with 'alt enter'. In my case it is 9342 x 7041 Pixels.
+Now woe need to get the height and the width of our plane.
+In my case:
+- X = 9342 * 50/97 = 4815 (m)
+- Y = 7041 * 50/97 = 3629 (m)
+
+Now we have our plane size. That we apply to our plane in Godot: 
+
+![Pic3](02-imgs/MapPlaneSize.png)
+
+Press 'ctrl s' ;) Now under the plane settings you will find a material. Create a new Spatial Material, click it, and under albedo you will see a empty texture field. Drag and Drop the large .png image to this empty texture field. This could take some seconds.
+After that it will look like this:
+
+![Pic4](02-imgs/AfterAddingMapGround.png)
+
+Select the Mesh Instance again. In the Inspector further below you will find Transformation Settings. Set the Rotation Degrees to: x: -90 y: -90 z: 0
+Now you could Adjust the Transformation from the Plane your track will start near the origin of the world. Also make sure to set the y coordinate to something below 0:
+
+![Pic5](02-imgs/MapPlaneTransformation.png)
+
+Great. Now your world is prepared for building!
+
+## Dos
+- Save often, save early.
+- Use version control or at least backup your files regularly.
+- Only use assets, if you have the rights for it. Best look for assets, which are licensed under [CC0](https://creativecommons.org/publicdomain/zero/1.0/deed.de). [OpenGameArt](https://opengameart.org/) is a nice site, where you find many assets licensed under CC0. (CC0 isn't required, but it makes a lot easier). [cc0textures](https://cc0textures.com/) has also very good textures. At the point we don't use normal maps etc, but if you want you could do this. Godot supports them.
+
+## Don'ts
+- Giving it up - If you have problem feel free to open a new issue. Together we will solve your Problem: [Click Here](https://github.com/Libre-TrainSim/Libre-TrainSim/issues/new). Feel free to contact Jean via Discord: https://www.libre-trainsim.de/links