diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 4c184d1..ae3155a 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/.wordlist.txt b/.wordlist.txt index f55e8e6..5c36a98 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1 +1,19 @@ -libre \ No newline at end of file +libre +unintuitive +trainsim +npc +thuringia +maglev +osm +png +GDScript +Shader +tscn +tres +cfg +AudioStreamPlayer +ogg +LTS +https +addon +addons \ No newline at end of file diff --git a/README.md b/README.md index 93ad65f..a39211c 100644 --- a/README.md +++ b/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. diff --git a/docs/contribute/code/index.md b/docs/contribute/code/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/contribute/file-structure.md b/docs/contribute/file-structure.md new file mode 100644 index 0000000..2722c67 --- /dev/null +++ b/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. + diff --git a/docs/contribute/getting-started.md b/docs/contribute/getting-started.md new file mode 100644 index 0000000..99a301c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/contribute/index.md b/docs/contribute/index.md index e69de29..7bcff24 100644 --- a/docs/contribute/index.md +++ b/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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 6769be3..a504535 100644 --- a/docs/index.md +++ b/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. \ No newline at end of file +► 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. \ No newline at end of file diff --git a/docs/manual/editor/00-index.md b/docs/manual/editor/00-index.md new file mode 100644 index 0000000..b6a5304 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/manual/editor/01-first-steps.md b/docs/manual/editor/01-first-steps.md new file mode 100644 index 0000000..da69a4a --- /dev/null +++ b/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) diff --git a/docs/manual/editor/01-imgs/map_example.png b/docs/manual/editor/01-imgs/map_example.png new file mode 100644 index 0000000..c03eebb Binary files /dev/null and b/docs/manual/editor/01-imgs/map_example.png differ diff --git a/docs/manual/editor/02-getting-started.md b/docs/manual/editor/02-getting-started.md new file mode 100644 index 0000000..b9737b7 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/manual/editor/02-imgs/AfterAddingMapGround.png b/docs/manual/editor/02-imgs/AfterAddingMapGround.png new file mode 100644 index 0000000..c835d42 Binary files /dev/null and b/docs/manual/editor/02-imgs/AfterAddingMapGround.png differ diff --git a/docs/manual/editor/02-imgs/CreateNewNodeInWorld.png b/docs/manual/editor/02-imgs/CreateNewNodeInWorld.png new file mode 100644 index 0000000..5f2c3b6 Binary files /dev/null and b/docs/manual/editor/02-imgs/CreateNewNodeInWorld.png differ diff --git a/docs/manual/editor/02-imgs/GroundAddingPlane.png b/docs/manual/editor/02-imgs/GroundAddingPlane.png new file mode 100644 index 0000000..21a5cf5 Binary files /dev/null and b/docs/manual/editor/02-imgs/GroundAddingPlane.png differ diff --git a/docs/manual/editor/02-imgs/MapPlaneSize.png b/docs/manual/editor/02-imgs/MapPlaneSize.png new file mode 100644 index 0000000..3d08e06 Binary files /dev/null and b/docs/manual/editor/02-imgs/MapPlaneSize.png differ diff --git a/docs/manual/editor/02-imgs/MapPlaneTransformation.png b/docs/manual/editor/02-imgs/MapPlaneTransformation.png new file mode 100644 index 0000000..0761546 Binary files /dev/null and b/docs/manual/editor/02-imgs/MapPlaneTransformation.png differ diff --git a/docs/manual/editor/04-building-rails.md b/docs/manual/editor/04-building-rails.md new file mode 100644 index 0000000..efef4a8 --- /dev/null +++ b/docs/manual/editor/04-building-rails.md @@ -0,0 +1,177 @@ +# Building Rails + +This article introduces the various features that aid rail building. + +You can move rails by dragging their end (red arrow). When dragged to another snapping point (red or green arrow), the editor can sometimes automatically insert a filler rail. However in most cases you'll need to tweak the numbers to create working switches. + +!!! note "Docs merging note" + Language needs to be revised. + +!!! danger "Update info" + Needs new screenshots. + +## Rail Builder + +Let's start with an overview of the `RailBuilder`. + +![SectionsOfRailBuilder](04-imgs/SectionsOfRailBuilder.jpg) + +1. Rename or delete the rail. +2. Add a new rail in one of these modes: + - *After Rail* adds a rail after the currently selected one. + - *Parallel To* adds a rail next to the currently selected rail. See the information below for more information. + - *Before Rail* adds a rail in front of the currently selected rail. +3. Shows read-only stats of the rails rotation, position, and height. +4. Defines the rail type. +5. Defines the rails geometry. All rails have two of the three following parameters: + - *Length* sets the length of the rail up to a maximum of `1000` metres. + - *Radius* sets the curveture. A radius of 0 is treated as a straight rail. A value of 100 is very sharp whereas a value of 10000 is almost straight. + - *Angle* sets the change in rotation. +6. Defines the slope of the rail. +7. Defines the tendency of the rail. +8. Press this `Update` button or `enter` in any field to apply changes. **There's no undo!** +9. Shows the calculated rail connections. + +!!! tip + The most used rail building mode is probably `Length - Angle` directly followed by `Length - Radius`. + +![1](04-imgs/1.png) + +`Manual Moving in Editor` prevents accidential movement of rails when deactivated. + +!!! warning "Weird UX" + Right now this setting is saved individually for each rail. + +## Basics in Rail Building + +Every rail has a start and an end arrow. The green one is the start point, the red one the end point. ![SimpleRail](04-imgs/SimpleRail.png) + +There's prelimary drag and drop support for rails when dragging their end arrow. Note though that most connections can't be made automatically. + +The route baking calculates connected rails at run-time by comparing the position and rotation of the rails. Here are some examples: + +- These rails are well connected. Trains can drive them perfectly. ![WellConnected](04-imgs/WellConnected.png) +- These rails are messily connected but trains can still use them. ![NotWellConnectedButTrainWillDetectIt](04-imgs/2.png) +- The position of both rails is perfectly aligned but their rotation is too different. Trains cannot drive them ![NotConnected1](04-imgs/NotConnected1.png) +- The rotation of both rails is perfect but the distance between them is too wide. Trains cannot use these, too. ![NotConnected2](04-imgs/NotConnected2.png) + +### Is there any other connection between the rails except the same location and rotation? + +No, there is no further magic. The routes are calculated every start of the game based on the rail locations and rotations. + +### How do switches work technically? + +Libre TrainSim does not have real switches. Switches are built by adding another rail to the end of a rail. That way multiple rails are connected. + +!!! note "Docs merging note" + This info here is very good. Perhaps this should be moved to an easier findable position. It doesn't really make sense in a step by step guide. + +## Switch Recipes + +Here, you'll find some blueprints for common switches. + +!!! note "Docs merging note + We should add step by step gifs here. + +### Basic Switch + +1. Determine where your switch should start. Here it starts at the end. +2. Select the rail and in the rail builder select `After Rail` and `New Rail`. You should end up something like this: ![BasicSwitch1](04-imgs/BasicSwitch1.png) +3. Now select the first rail and add a new rail after it again. Change the radius or angle and update it. ![BasicSwitch2](04-imgs/BasicSwitch2.png) + +Congratulations! You built your first switch! + +### One-way to two-way switch + +1. Start with a straight rail, add a rail after it, and adjust the length of it. (It will later be the length of the whole curve) Start with something like 150 metres. +2. Add another rail to the newly created rail. ![AdvancedSwitch1_1](04-imgs/AdvancedSwitch1_1.png) +3. Select the newly created, third rail and add a parallel rail. Set the distance to something like `4.5` metres. +4. Select the new one and create a new rail after it. +5. Drag the end of the rail to the other beginning. A popup prompting to fix the rail connection opens. +6. Click `OK`. +7. The result should look like this: ![AdvancedSwitch1_3](04-imgs/AdvancedSwitch1_3.png) + +### Curved Switch + +1. Start with a rail, add one after it, and set its angle to `10` degrees and its length to `100` metres. +2. Add another rail after, and add a parallel rail whith a distance of `-4.5` metres. ![AdvancedSwitch2_1](04-imgs/AdvancedSwitch2_1.png) +3. Select the first rail, add another rail after it. +4. Set the new rails angle to the same as the other switch leg (it's the value used in step one, so `10` in this example). +5. Reduce the length as much as possible to create the longest straight line possible between the new leg and the other parallel rail. `45` metres seem good in this example. ![AdvancedSwitch2_2](04-imgs/AdvancedSwitch2_2.png) +6. Connect both rails by dragging one end. ![AdvancedSwitch2_3](04-imgs/AdvancedSwitch2_3.png) + +### Double Cross + +1. Start with a straight rail and add three rails with the same length. +2. Add another rail that can be as long as you want. +3. Add two parallel rails as shown. ![AdvancedSwitch3_1](04-imgs/AdvancedSwitch3_1.png) +4. Connect rails one and two and rails three and four by dragging the rails. ![AdvancedSwitch3_2](04-imgs/AdvancedSwitch3_2.png) +5. Connect rails five and six. +6. Delete any unwanted rails. ![AdvancedSwitch3_3](04-imgs/AdvancedSwitch3_3.png) + +## Slope + +!!! warning + This feature is unstable. Please notify us of any issues you come across. + +Rails can change height by changing their slope settings. Slopes are defined at the start and end points. + +!!! note + Slopes is calculated as a circle. + +![Slope1](04-imgs/Slope1.png) + +Slopes are also applied to parallel rails and can be combined with tendency. + +!!! warning + The big issue with our slope implementation is controlling the height. While it's possible - as demonstrated in the rail curve settings - it is deemed unnecessarily complex right now. This stance may change in the future when terrain gets implemented. + +1. Add a `50` metres long rail and set the start slope to `0` and the end slope to `7`. +2. Add a rail behind and set its length to 200. +3. The end height of the rail is now `15.74646`. To get to almost exact 20 meters, add another rail and set its end slope to `0`. +4. Reduce the length until the end height is reached. + +![Slope2](04-imgs/Slope2.png) + +!!! warning + Do not build switches since parallel rails are the only ones supporting matched slopes. Drag and drop will not work either. + + While you could tweak values until the rails work, it's going to be messy and a pain in the a... + +## Tendency + +Train curves work because certain forces work against each other. Tilting helps to increase the inward force and as such allows curves to be driven faster. + +### Simple Tendency + +The tendency is defined by a start and end value. In this example the rail is 200 metres long and the tilt is set to `4` degrees at both start and end points. ![Tendency1](04-imgs/Tendency1.png) + +You need another rail in front and one behind that tilt into and out of the curve with this setup. + +### Advanced Tendency + +!!! tip + Use automatic tendency. It will ease your life significantly. + + Manual setting of these values is considered bad UX and may be removed entirely in favor of the automatic approach. Please let us know if you have a non-covered use case. + +In the real world clothoids are used. They are special because they continously transition into the curve. Thus the tilt can also slowly transition. However as we don't have them, we have to tilt the adjacent rails or use the method described hereafter. + +![AdvancedTendency1](04-imgs/AdvancedTendency1.png) + +You can use three or four tendency points to describe the transition, too. To use only three points, set the position of `Tend Point2` to `-1`. ![AdvancedTendency2](04-imgs/AdvancedTendency2.png) + +In this example we use two points. Since the curve is about a hundred metres long, we assert a fifth on each side for the transition. ![AdvancedTendency3](04-imgs/AdvancedTendency3.png) + +![AdvancedTendency4](04-imgs/AdvancedTendency4.png) + +## Parallel Rails + +!!! note "Docs merging note" + Still valid? Not revised. + +Parallel rails are specially treated. They inherent their values from the linked rail. The only setting you can adjust is the offset to the linked rail. If the linked rail is deleted, the rail becomes useless and needs to be deleted, too. + +--- + +## [YouTube Video](https://youtu.be/p0ycRpTUvfM) diff --git a/docs/manual/editor/04-imgs/1.png b/docs/manual/editor/04-imgs/1.png new file mode 100644 index 0000000..700a363 Binary files /dev/null and b/docs/manual/editor/04-imgs/1.png differ diff --git a/docs/manual/editor/04-imgs/2.png b/docs/manual/editor/04-imgs/2.png new file mode 100644 index 0000000..4089d78 Binary files /dev/null and b/docs/manual/editor/04-imgs/2.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch1_1.png b/docs/manual/editor/04-imgs/AdvancedSwitch1_1.png new file mode 100644 index 0000000..97b7df5 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch1_1.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch1_2.png b/docs/manual/editor/04-imgs/AdvancedSwitch1_2.png new file mode 100644 index 0000000..2e673e4 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch1_2.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch1_3.png b/docs/manual/editor/04-imgs/AdvancedSwitch1_3.png new file mode 100644 index 0000000..cdbd417 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch1_3.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch2_1.png b/docs/manual/editor/04-imgs/AdvancedSwitch2_1.png new file mode 100644 index 0000000..d810f65 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch2_1.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch2_2.png b/docs/manual/editor/04-imgs/AdvancedSwitch2_2.png new file mode 100644 index 0000000..b20a06c Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch2_2.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch2_3.png b/docs/manual/editor/04-imgs/AdvancedSwitch2_3.png new file mode 100644 index 0000000..64328c2 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch2_3.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch3_1.png b/docs/manual/editor/04-imgs/AdvancedSwitch3_1.png new file mode 100644 index 0000000..8b15127 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch3_1.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch3_2.png b/docs/manual/editor/04-imgs/AdvancedSwitch3_2.png new file mode 100644 index 0000000..3eb2418 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch3_2.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedSwitch3_3.png b/docs/manual/editor/04-imgs/AdvancedSwitch3_3.png new file mode 100644 index 0000000..2589ab4 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedSwitch3_3.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedTendency1.png b/docs/manual/editor/04-imgs/AdvancedTendency1.png new file mode 100644 index 0000000..b70cb40 Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedTendency1.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedTendency2.png b/docs/manual/editor/04-imgs/AdvancedTendency2.png new file mode 100644 index 0000000..801d66b Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedTendency2.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedTendency3.png b/docs/manual/editor/04-imgs/AdvancedTendency3.png new file mode 100644 index 0000000..eab479b Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedTendency3.png differ diff --git a/docs/manual/editor/04-imgs/AdvancedTendency4.png b/docs/manual/editor/04-imgs/AdvancedTendency4.png new file mode 100644 index 0000000..1c9d58b Binary files /dev/null and b/docs/manual/editor/04-imgs/AdvancedTendency4.png differ diff --git a/docs/manual/editor/04-imgs/BasicSwitch1.png b/docs/manual/editor/04-imgs/BasicSwitch1.png new file mode 100644 index 0000000..2143ef3 Binary files /dev/null and b/docs/manual/editor/04-imgs/BasicSwitch1.png differ diff --git a/docs/manual/editor/04-imgs/BasicSwitch2.png b/docs/manual/editor/04-imgs/BasicSwitch2.png new file mode 100644 index 0000000..ade9753 Binary files /dev/null and b/docs/manual/editor/04-imgs/BasicSwitch2.png differ diff --git a/docs/manual/editor/04-imgs/NotConnected1.png b/docs/manual/editor/04-imgs/NotConnected1.png new file mode 100644 index 0000000..bdc9862 Binary files /dev/null and b/docs/manual/editor/04-imgs/NotConnected1.png differ diff --git a/docs/manual/editor/04-imgs/NotConnected2.png b/docs/manual/editor/04-imgs/NotConnected2.png new file mode 100644 index 0000000..6e10c5e Binary files /dev/null and b/docs/manual/editor/04-imgs/NotConnected2.png differ diff --git a/docs/manual/editor/04-imgs/RailConnector1.png b/docs/manual/editor/04-imgs/RailConnector1.png new file mode 100644 index 0000000..dac3ddd Binary files /dev/null and b/docs/manual/editor/04-imgs/RailConnector1.png differ diff --git a/docs/manual/editor/04-imgs/RailConnector2.png b/docs/manual/editor/04-imgs/RailConnector2.png new file mode 100644 index 0000000..ccc9520 Binary files /dev/null and b/docs/manual/editor/04-imgs/RailConnector2.png differ diff --git a/docs/manual/editor/04-imgs/SectionsOfRailBuilder.jpg b/docs/manual/editor/04-imgs/SectionsOfRailBuilder.jpg new file mode 100644 index 0000000..c4d5771 Binary files /dev/null and b/docs/manual/editor/04-imgs/SectionsOfRailBuilder.jpg differ diff --git a/docs/manual/editor/04-imgs/SectionsOfRailBuilder.png b/docs/manual/editor/04-imgs/SectionsOfRailBuilder.png new file mode 100644 index 0000000..2a4f562 Binary files /dev/null and b/docs/manual/editor/04-imgs/SectionsOfRailBuilder.png differ diff --git a/docs/manual/editor/04-imgs/SimpleRail.png b/docs/manual/editor/04-imgs/SimpleRail.png new file mode 100644 index 0000000..baa7cb0 Binary files /dev/null and b/docs/manual/editor/04-imgs/SimpleRail.png differ diff --git a/docs/manual/editor/04-imgs/Slope1.png b/docs/manual/editor/04-imgs/Slope1.png new file mode 100644 index 0000000..e39cf86 Binary files /dev/null and b/docs/manual/editor/04-imgs/Slope1.png differ diff --git a/docs/manual/editor/04-imgs/Slope2.png b/docs/manual/editor/04-imgs/Slope2.png new file mode 100644 index 0000000..86d7847 Binary files /dev/null and b/docs/manual/editor/04-imgs/Slope2.png differ diff --git a/docs/manual/editor/04-imgs/Tendency1.png b/docs/manual/editor/04-imgs/Tendency1.png new file mode 100644 index 0000000..4d9e65e Binary files /dev/null and b/docs/manual/editor/04-imgs/Tendency1.png differ diff --git a/docs/manual/editor/04-imgs/WellConnected.png b/docs/manual/editor/04-imgs/WellConnected.png new file mode 100644 index 0000000..abdffe1 Binary files /dev/null and b/docs/manual/editor/04-imgs/WellConnected.png differ diff --git a/docs/manual/editor/05-imgs/4.png b/docs/manual/editor/05-imgs/4.png new file mode 100644 index 0000000..8deb4bd Binary files /dev/null and b/docs/manual/editor/05-imgs/4.png differ diff --git a/docs/manual/editor/05-imgs/5.png b/docs/manual/editor/05-imgs/5.png new file mode 100644 index 0000000..d2196e1 Binary files /dev/null and b/docs/manual/editor/05-imgs/5.png differ diff --git a/docs/manual/editor/05-imgs/6.png b/docs/manual/editor/05-imgs/6.png new file mode 100644 index 0000000..4f2fcc6 Binary files /dev/null and b/docs/manual/editor/05-imgs/6.png differ diff --git a/docs/manual/editor/05-imgs/HowToMakeConfigureARoute.png b/docs/manual/editor/05-imgs/HowToMakeConfigureARoute.png new file mode 100644 index 0000000..3604fe6 Binary files /dev/null and b/docs/manual/editor/05-imgs/HowToMakeConfigureARoute.png differ diff --git a/docs/manual/editor/05-imgs/dirty_world_configuration.png b/docs/manual/editor/05-imgs/dirty_world_configuration.png new file mode 100644 index 0000000..fba79ec Binary files /dev/null and b/docs/manual/editor/05-imgs/dirty_world_configuration.png differ diff --git a/docs/manual/editor/05-quick-test-setup.md b/docs/manual/editor/05-quick-test-setup.md new file mode 100644 index 0000000..e6c1144 --- /dev/null +++ b/docs/manual/editor/05-quick-test-setup.md @@ -0,0 +1,45 @@ +# Quick and dirty track testing + +!!! note "Docs merging note" + Workflow is completely different now. I wouldn't recommend creating tracks without adding stations because temporary stations are easily addable. Also requires switching to the scenario editor. + + +If you built some track, you definitively want to test your track out. We will do this very fast. For more details look in the chapters how scenarios and the world is set up. + +1. Select `Configuration` next to the RailBuilder Tab (Maybe you have to use white arrows at the end of the tab list) + +2. Fill in the World Config, its completely irrelevant, what you insert there. After that press `Save World Config`. + +3. Select `All Chunks` and click `Unload and Save Chunks`. After that your world should be empty. **Everytime you changed/added a rail, or changed something in `Buildings`, `Flora` or `TrackObjects` and want to test out your track, you have to unload and save chunks before.** After testing you could load all Chunks again. + +![3](05-imgs/dirty_world_configuration.png) + +4. Switch to the `Scenarios` tab. + +5. Create here a new scenario by writing something in (1) and then press `New` (2). + +6. Press at `Save General` and at `Save current Signal Data to scenario` **Every time you changed something important for your Scenario in `Signals`, you have to save the current Data to the scenario** If you don't have any Signals yet, you can ignore this. But `Save current Signal Data to Scenario` You should press even so. + +![4](05-imgs/4.png) + +7. Head over to `Trains` write 'Player' in the text field, and click on new. + +8. Insert the name of the Rail, the train will start. at `Start Rail`. Also you can define the Direction of the Train at the Start Rail. + +9. If you want, that the train drives a specific route over your world, you can insert the names of the rails he should definitely pass into the `Route` field. Seperate the Rails with a blank (` `). That field can be completely empty too. This is completely optional. + +![HowToAddARoute](05-imgs/HowToMakeConfigureARoute.png) + +10. Press in the End `Save Train` + +![5](05-imgs/5.png) + +11. Click at the play icon in the top right corner, and select your track from the Main Menu. + +![6](05-imgs/6.png) + +12. By pressing `Ctrl` + `Y` you can toggle debug mode. with it you can drive very fast. Have fun at testing! + +*** + +## YouTube Video: [Click here](https://youtu.be/RmR11yhq1D8) \ No newline at end of file diff --git a/docs/manual/editor/06-imgs/1.png b/docs/manual/editor/06-imgs/1.png new file mode 100644 index 0000000..bb50303 Binary files /dev/null and b/docs/manual/editor/06-imgs/1.png differ diff --git a/docs/manual/editor/06-imgs/10.png b/docs/manual/editor/06-imgs/10.png new file mode 100644 index 0000000..71ac3b8 Binary files /dev/null and b/docs/manual/editor/06-imgs/10.png differ diff --git a/docs/manual/editor/06-imgs/11.png b/docs/manual/editor/06-imgs/11.png new file mode 100644 index 0000000..25df558 Binary files /dev/null and b/docs/manual/editor/06-imgs/11.png differ diff --git a/docs/manual/editor/06-imgs/12.png b/docs/manual/editor/06-imgs/12.png new file mode 100644 index 0000000..71fb736 Binary files /dev/null and b/docs/manual/editor/06-imgs/12.png differ diff --git a/docs/manual/editor/06-imgs/13.png b/docs/manual/editor/06-imgs/13.png new file mode 100644 index 0000000..10006aa Binary files /dev/null and b/docs/manual/editor/06-imgs/13.png differ diff --git a/docs/manual/editor/06-imgs/2.png b/docs/manual/editor/06-imgs/2.png new file mode 100644 index 0000000..f82bdb8 Binary files /dev/null and b/docs/manual/editor/06-imgs/2.png differ diff --git a/docs/manual/editor/06-imgs/3.png b/docs/manual/editor/06-imgs/3.png new file mode 100644 index 0000000..a8de4b2 Binary files /dev/null and b/docs/manual/editor/06-imgs/3.png differ diff --git a/docs/manual/editor/06-imgs/4.png b/docs/manual/editor/06-imgs/4.png new file mode 100644 index 0000000..b3c120b Binary files /dev/null and b/docs/manual/editor/06-imgs/4.png differ diff --git a/docs/manual/editor/06-imgs/5.png b/docs/manual/editor/06-imgs/5.png new file mode 100644 index 0000000..57560d0 Binary files /dev/null and b/docs/manual/editor/06-imgs/5.png differ diff --git a/docs/manual/editor/06-imgs/6.png b/docs/manual/editor/06-imgs/6.png new file mode 100644 index 0000000..9efa58b Binary files /dev/null and b/docs/manual/editor/06-imgs/6.png differ diff --git a/docs/manual/editor/06-imgs/7.png b/docs/manual/editor/06-imgs/7.png new file mode 100644 index 0000000..02d7ab7 Binary files /dev/null and b/docs/manual/editor/06-imgs/7.png differ diff --git a/docs/manual/editor/06-imgs/8.png b/docs/manual/editor/06-imgs/8.png new file mode 100644 index 0000000..4469754 Binary files /dev/null and b/docs/manual/editor/06-imgs/8.png differ diff --git a/docs/manual/editor/06-imgs/9.png b/docs/manual/editor/06-imgs/9.png new file mode 100644 index 0000000..250d733 Binary files /dev/null and b/docs/manual/editor/06-imgs/9.png differ diff --git a/docs/manual/editor/06-station-setup.md b/docs/manual/editor/06-station-setup.md new file mode 100644 index 0000000..b301c02 --- /dev/null +++ b/docs/manual/editor/06-station-setup.md @@ -0,0 +1,91 @@ +# Station Setup + +!!! note "Docs merging note" + Just images copied. Language and content not verified. I imagine it's roughly the same. + +Lets build a train station. You already should have built your rails. This is, how we gonna start: + +![1](06-imgs/1.png) + + +## Platform + +My train station will be 135 m long, and there will be a platform in the middle. Lets build our first Objects to the track. For that you have to open the tab `Rail Attachments` next to the Track Builder Tab, and select a rail. It will look like this: + +![2](06-imgs/2.png) + +Lets add a new Track Object by typing in the field e.g. `Platform` and by pressing the `New` button. In the end select your newly added entry. In the end it will look like this: + +![3](06-imgs/3.png) + +You now need to specify a .obj file for your object. Select `Pick`and select `Platform-1_double.obj` in `res://Resources/Basic` for example. Alternatively you can paste your path `res://Resources/Basic/Platform-1_double.obj` to the text field. *(Of course you can later select your own custom object. But for that read the article about adding your own content to Libre TrainSim)* + +Now select the Tab `Position` and make sure `Assign WholeRail` is activated. Then your platform will be set over the whole rail. Alternatively you can define a specific position. Now click on `Save`. + +Select the tab `Object Positioning` and adjust the values like below: + +![4](06-imgs/4.png) + +Press `Save` and `Ùpdate`. If everything goes right, then you should see a crappy looking platform. + +![5](06-imgs/5.png) + +That's because we didn't set the Materials properly. Under `Object` you can add Materials. Click on `Add` under Materials and select `pick` and select following Materials. They should have the same order. + +![6](06-imgs/6.png) + +If you accidently added more Materials than in this case 3, just leave them empty, Libre TrainSim will recognize that. In the end it will look like this: + +![7](06-imgs/7.png) + +Now add platforms on the other train stations too. To copy a TrackObject just select `Copy` under the list, select another rail, and select `Paste`. (Of course you can later change the platforms, and detail your platforms better. + +## Adding Train Station Logic +Now we need to say to Libre TrainSim where a Train Station is. For that navigate in the `FileSystem` tab at the left bottom corner to `res://addons/Libre_Train_Sim_Editor/Data/Modules/`. *(You can also search for `Station` in the FileSystem, that's faster.)* Select the rail, where you want to assign the train station. Now drag and drop `Station.tscn` to the 3D View. + +![8](06-imgs/8.png) + +Now select the new blue sphere, and select the Inspector on the right screen. Here you can define the Station Length, Position, and much more. After that select `Update`. Also it is recommended to rename the train station. In this Example the settings are: + +![9](06-imgs/9.png) + +Now repeat this at every wail, which whether ai trains or the player should halt at a station. +For the other rail (on which the trains will halt at the other direction) the settings look like this: + +![10](06-imgs/10.png) + +**Attention**: Please keep in mind, that you shouldn't order any nodes in the Scene Tree. Every Rail should be a direct child of `Rails`, every signal, train station, speed limit... should be a direct child of `Signals`, and so on. ;) + +![11](06-imgs/11.png) + +## Creating Simple Timetable for testing route +**Make sure you followed the article 'Testing Your Track') properly, or this will not work** +You now should have defined every train station node. Lets create a timetable for our player train, that Libre TrainSim knows, on which station and when the train should halt. +Select the `Configuration` Tab, select or create a new scenario, select `Trains`, and then select or create a train called `Player` +It should now look similar to this: + +![12](06-imgs/12.png) + +Fill in the route, (like in the article 'Testing Your Track' described), and add timetable entrys. It should be self explaining. +- Under `Node Name` insert the name of the station node, which we defined above. +- Under `Station Name` insert the name of the station how it is called ingame +- Arrival Time and Departure Time are self explaining. For just testing you could leave them at 0. +- Minimal Halt Time: How long the train should halt at a minimum. (Unit: Seconds) +- StopType is self explaining too. + +In the end my timetable looks like this: + +![13](06-imgs/13.png) + +Make sure you select `Save Train` in the End + +Now you could test it out! (Press ctrl a in the train to activate the autopilot to get a neutral reference. How this track is driven in the end. + +If your train does not hold at a station, you wanted: +- Is the Node Name written in the Time table correctly? +- Is the Train Station placed in the correct direction? (Check Forward Property at the Train Station Node) +- Is the halt type correctly set in the timetable? + +*** + +### YouTube Video: [Click here](https://youtu.be/yOFAHt3I9D8) \ No newline at end of file diff --git a/docs/manual/editor/07-imgs/1.png b/docs/manual/editor/07-imgs/1.png new file mode 100644 index 0000000..9721444 Binary files /dev/null and b/docs/manual/editor/07-imgs/1.png differ diff --git a/docs/manual/editor/07-imgs/2.png b/docs/manual/editor/07-imgs/2.png new file mode 100644 index 0000000..1728a4b Binary files /dev/null and b/docs/manual/editor/07-imgs/2.png differ diff --git a/docs/manual/editor/07-imgs/3.png b/docs/manual/editor/07-imgs/3.png new file mode 100644 index 0000000..436c6ce Binary files /dev/null and b/docs/manual/editor/07-imgs/3.png differ diff --git a/docs/manual/editor/07-imgs/4.png b/docs/manual/editor/07-imgs/4.png new file mode 100644 index 0000000..9d70680 Binary files /dev/null and b/docs/manual/editor/07-imgs/4.png differ diff --git a/docs/manual/editor/07-imgs/5.png b/docs/manual/editor/07-imgs/5.png new file mode 100644 index 0000000..4253c6e Binary files /dev/null and b/docs/manual/editor/07-imgs/5.png differ diff --git a/docs/manual/editor/07-imgs/6.png b/docs/manual/editor/07-imgs/6.png new file mode 100644 index 0000000..4edd9af Binary files /dev/null and b/docs/manual/editor/07-imgs/6.png differ diff --git a/docs/manual/editor/07-imgs/7.png b/docs/manual/editor/07-imgs/7.png new file mode 100644 index 0000000..f959963 Binary files /dev/null and b/docs/manual/editor/07-imgs/7.png differ diff --git a/docs/manual/editor/07-rail-logic.md b/docs/manual/editor/07-rail-logic.md new file mode 100644 index 0000000..8c33f91 --- /dev/null +++ b/docs/manual/editor/07-rail-logic.md @@ -0,0 +1,91 @@ +# Rail Logic + +!!! note "Docs merging note" + Feels like a good reference article. Less so in a step by step guide though. Language and content not verified. Screenshots outdated. + I feel like we should also present all the different signalling systems on another page. + +## Basics +Why are signals, train stations, speed limits, and contact points handled in one article? Because technically they are very similar, and work all same. + +***Technical Background***: A signal point registers itself at his attached rail. This attached rails saves all signal points with position, which are attached to it in a list. If a train drives over this rail, the train takes this list with all signal points and checks, from now on, if he drove over a signal point. If he drove over it, and it has the same direction as the train self, the train activates a 'signal' function in itself and that function decides dependent of the type what to do. That works for all types of signals (signals, train stations, speed limits...). (From version 0.6 the train is more intelligent, and could search in his route for the next signal. That makes for example the autopilot possible). + +So what similarities do they all have together? +- The way how the train recognize them +- They are always attached to a rail on a specific rail position, with a specific direction. +- The way how you add them into the world + +**How to add a signal point:** +- At first select the rail, on which you want to add the signal point. +- Open in the the FileSystem at the bottom left corner the following path: `res://addons/Libre_Train_Sim_Editor/Data/Modules` Here you see all basic Modules of which Libre TrainSim exists without the Train ;). From here you can drag and drop a module to the 3d view. These signal points you could add: + - ContactPoint.tscn + - SpeedLimit.tscn + - Signal.tscn + - Station.tscn + - WarnSpeedLimit.tscn + +![1](07-imgs/1.png) + +- Select the signal in the 3D View, and then you could define in the Inspector the rail position and the direction. + +![2](07-imgs/2.png) + +- In my case I set it to the following properties. My rail is 135 m long: + +![3](07-imgs/3.png) + +Great! You now know the basics about signals points. + +## 'Normal Signals': +Since version 0.8 you can create your own visual instances for signals and can specify the path under `Visual Instance Path` of a signal. For creating own visual instances for signals an article will follow. + +![4](07-imgs/4.png) + +So well, the basic function of a signal is very very easy. Its the status variable: Is the status set to 0, the signal is red, and no train should pass. If the status is set to 1, then its green or orange, and the train can pass the signal. + +With the `Set Pass At ...` Variables you can define a time, when the signal sets its status to 1. That is very useful at signals at a station. *(This could happen just one time ingame. Generally it is recommended just to use this functions for the "Player" train.)* + +![5](07-imgs/5.png) + +In This example the signal is set to status = 1 at 14:30:00 or 02:30:00 pm. + +Also you can define a speed limit in km/h which should be applied, if the train drives over it. If it is set to -1, then this is ignored. + +**How can I configure, that the signal shows orange, or a Warn Speed Limit (orange digits)?** That is set automaticly by the signal. *(All trains are configuring at the beginning of the simulation the signals, and "say" them, which signal they will drive over after the signal. From there the signal checks the status and the speed limit "after" the signal it self, and set itself if necessary to orange, or/and shows the orange digits.)* + +- Green: Train can pass (Status 1) +- Orange: Train can pass, next signal shows red. (Status 1) +- Red: Train should not pass. (Status 0) + +**Block Signal**: If this mode is active, then the signal works 'automaticly'. At default the signal is green. It turns red, when a train drives over, and will turn green again, if the train drives over the signal behind it. (The signal behind it don't have to be a Block Signal necessarily. When a train despawns, the signal will recognize it also). *The only point: THe Block Signal don't recognize, when a train spawns behind it. It only turns red, when a train drives over it.* + +## Contact Points: +What does a Contact Point? If a (optional: specific) train drives over it, the contact point activates (optional: after some seconds) a signal, end set it to a defined status and speed. With that feature complex Signal Processes are possible. + +![6](07-imgs/6.png) + +- **Affected Signal**: The Signal Name in the scene tree of the Affected Signal. +- **By Specific Train**: If the Contact point should be activated by a specific Train. (Name of it). If every train, who drives over it, should activate this point, that variable has to be empty. +- **New Status**: Self explaining +- **New Speed**: Self explaining +- **Affect Time**: Time in seconds, after it the signal should be set. Set it to `0` if the signal should set immediately. + +In the example above the signal called `Signal` will be set to status = 1 with speed 80 5 seconds after any train drove over this contact point. + +## Station: +Look to article 'Train Stations' for more details. + +## Speed Limit: +First of all: At the moment it is not easy/possible to change the signals look or model. That will be implemented for version 0.8. + +Very simple: +If a train drives over it, the speed limit which is set in the variable `Speed` will be applied. It shouldn't/can't be changed Ingame, because it is a static sign ;) + +![7](07-imgs/7.png) + +## Warn Speed Limit: +First of all: At the moment it is not easy/possible to change the signals look or model. That will be implemented for version 0.8. + +That's even simler than the normal Speed Limit. It just announce the player, which speed limit is the next one. *(Normally just set, if the next speed limit is lower than the current one)*. +It doesn't set itself automatically, or has any effect to the trains. + +### YouTube Video: [Click here](https://youtu.be/OMS1oaVrfwA) \ No newline at end of file diff --git a/docs/manual/editor/08-adding-landscape.md b/docs/manual/editor/08-adding-landscape.md new file mode 100644 index 0000000..5c75aa8 --- /dev/null +++ b/docs/manual/editor/08-adding-landscape.md @@ -0,0 +1,109 @@ +# Adding Landscape + +!!! note "Docs merging note" + This article is less about adding landscape and more about using the rail attachments thingy. While that's fine, we should also include docs about leveldesign and how to make the map nice. Think about guidance and how to make it memorable and nice looking. + + Content and language not verified. Screenshots and workflow questionable. + +Now all your rails, Train Stations, and Signals should be final. (*Of course you could change/improve these later too, but it is easier if you from now only can focus on landscape building)* + +## General: +- It is highly recommended to start with the very important objects, and end with the unimportant things. Example: + 1. Rail Assets like catenary poles, tunnels, bridges, dams + 2. Train station's Decoration and buildings + 3. Very important / marked buildings, rivers, lakes.., mountains... + 4. Near Objects at the track like noise barriers, near vegetation + 5. Settlements, normal houses, roads + 6. Vegetation + 7. The remaining things :) + +- There are different types how you can build Landscape Elements: + - **Simple Objects/Mesh Instances**: These are single objects, which should be used for Very important / marked buildings, rivers, lakes. Or said, if you just want to build under 5 instances of an object. + - **Track Objects**: Maybe you got to know this feature in building Tran Stations. You can use this for adding catenary poles, tunnels, bridges, dams, train station's decoration, noise barriers, (settlements, normal houses, vegetation, ..) The Track objects position their objects aligned to a rail. These objects could be also positioned very far away from the rails. + - **Forests**: These type is called forest, but could be used for settlements, normal houses, vegetation, car parks, ... tooo. The only difference between Forests and Track Objects is: Track Objects are aligned to the rail, and Forests not. Tadaaa! + +- The current maximal view distance is 1000m. Libre TrainSim has a chunk system, which organize all objects into chunks, and just loads them, if the player is near to this chunk. But for normal train tracks you generally won't need to build detailed objects, which are more than 200m away from the track. +- Just build objects, you could see from the inner view of a train ;) +- Try to reuse Materials! Under `res://Resources/Basic/Materials/` you find many pre-configured Materials. The good aspect at them: They will be updated with newer versions, and will look nicer over the time. If you use your own materials, they won't be updated unless you will update your materials. + +## Simple Objects/Mesh Instances +**Attention:** Simple Objects/Mesh Instances cost the most performance. If you want to add more equal objects which don't have a big distance to each other, use a Forest or a Track Object instead. They are using the Graphic Card Directly (MultiMeshes , yeah!). Try to use Track Objects as much you can, they are really powerful. + +All Simple Objects/Mesh Instances are saved under the node Buildings. As usually they should be direct children of the nodes `Buildings` in the Scene Tree. +Let's add a simple House: At first Make sure, that another Simple Object, the `Buildings` Node, or the `World` Node is selected. For that drag and drop a .obj File of the `FileSystem` Tab into the Scene: + +![1](08-imgs/1.png) + +The building looks very crapy. Lets assign Materials to it. At first select in the `Inspector` Tab under `Mesh` `Make Unique`. + +![2](08-imgs/2.png) + +Under `Material` you can now assign the materials. These Material Groups come defined with the .obj file *(I guess, maybe the .mtl file)*. For assigning a material, search for a material in the `FileSystem` tab. Under `res://Resources/Basic/Materials/` you will find some materials of Libre TrainSim, which are recommended to be used. If you don't find a material you need, you could create your own Material in Godot, and save it under `/Resources/YourTrackName`. It would be great, if you could share that material with the community, that it maybe will be put to `/Resources/Basic` later. For material creating in Godot read more Information [here](https://docs.godotengine.org/en/stable/tutorials/3d/spatial_material.html). + +If you found your Material, simply drag and drop it to the Material Slot. Repeat that until you are finished. + +![3](08-imgs/3.png) + +Now you can position it with the Gizmos in the 3D View. If you don't see them. Make sure, the Object is selected, and you pressed `Q` In the End it will look like this: + +![4](08-imgs/4.png) + +**Hint:** To duplicate the object, press `Ctrl D` + +## Track Objects: +For that there exists a Tool from Libre TrainSim. Probable you used it already for Train Stations. Select the Tab `Rail Attachments`. And select the rail, to which you want to assign the new Track Object, type a name in the text line and select `New`. After it select the new Track Object in the List. + +![5](08-imgs/5.png) + +Please have in mind: Never change a name of a Rail after adding some Track Object. You can find all Track Objects under the Node `TrackObjects`. Dont change any variable of them. Please just use the delivered tool for editing them. + +Now there are three Tabs available: + +### Objects +Here you can define the .obj File of the object, and and the Materials. (Maybe you will define the materials at a later point. That's completely okay. + +### Position +Here you define on which positions the Track Object should be. +The Unit is meters. + +**After changing the settings, you should press `Save`, and after that `Update`. + +### Object Positioning: +Here comes the fun. You can do almost every setting: + +![6](08-imgs/6.png) + +- **Side**: That is self explaining. Left and Right is mesured in the Rail direction. From green to red dot. +- **Spacing Straight**: Distance between the objects in "rail direction". +- **Spacing Left/Right**: Distance betwen the objects in the "left/right direction". Only to be attended if you are using more than 1 row. +- **Shift Left/Right**: Defines the "beginning" of the Track Object. If you want, that your Track Object should be placed 30 m next to the rail, then insert here 30. +- **Spawn Rate**: In here comes randomness: If it is set to 1: Then all Objects are placed. If it is set to e.g. 0.2, then theres only a chance of 20 % that a single object will be placed. That setting is prefect for forests. And makes the very boring Track Object a bit interesting. +- **Rows**: How many "rows" should be placed of the object? For that you should define `Shift Left/Right` too. +- **Height**: Generally a track object will follow the height of the track. But here you can define, if the height should be different to the tracks height. +- **Rotation** Here you can define the y-rotation of every object in degrees. +- **Place Last** Depending which objects you are placing, `Place Last` could be very usefull. It simply places additional object(s) at the end of the Track Objects. Rows is not influenced by that setting. It is referncing just the placing in "rail direction" +- **Apply Slope Rotation** Should be self explaining. Very usefully for tunnels or platforms at rising rails. +- **Random Location**: If activated, the location of a single object is a bit random. "How random" it is, can be defined with the `Max Moved Location` Variable. 0 means no random location. 1 means very random location. (With this some objects can intersect each other) +- **Random Rotation**: Self explaining +- **Random Rotation**: Like `Random Location`, just with scale. + +**After changing the settings, you should press `Save`, and after that `Update`. + +Here are some example configurations: + +**Some houses**:: + +![7](08-imgs/7.png) + +**Simple Forest**: + +![8](08-imgs/8.png) + +**Poles**: + +![9](08-imgs/9.png) + + +**Hint**: You are able to copy one or more track objects at the same time (select multiple with `Ctrl` pressed) between other track objects. That's very powerful and saves a lot of time. + +### YouTube-Video: [Click Here](https://youtu.be/b43HTepz4nM) \ No newline at end of file diff --git a/docs/manual/editor/08-imgs/1.png b/docs/manual/editor/08-imgs/1.png new file mode 100644 index 0000000..5d92e56 Binary files /dev/null and b/docs/manual/editor/08-imgs/1.png differ diff --git a/docs/manual/editor/08-imgs/2.png b/docs/manual/editor/08-imgs/2.png new file mode 100644 index 0000000..5d7fa7e Binary files /dev/null and b/docs/manual/editor/08-imgs/2.png differ diff --git a/docs/manual/editor/08-imgs/3.png b/docs/manual/editor/08-imgs/3.png new file mode 100644 index 0000000..768981e Binary files /dev/null and b/docs/manual/editor/08-imgs/3.png differ diff --git a/docs/manual/editor/08-imgs/4.png b/docs/manual/editor/08-imgs/4.png new file mode 100644 index 0000000..0156122 Binary files /dev/null and b/docs/manual/editor/08-imgs/4.png differ diff --git a/docs/manual/editor/08-imgs/5.png b/docs/manual/editor/08-imgs/5.png new file mode 100644 index 0000000..a471735 Binary files /dev/null and b/docs/manual/editor/08-imgs/5.png differ diff --git a/docs/manual/editor/08-imgs/6.png b/docs/manual/editor/08-imgs/6.png new file mode 100644 index 0000000..f8609f1 Binary files /dev/null and b/docs/manual/editor/08-imgs/6.png differ diff --git a/docs/manual/editor/08-imgs/7.png b/docs/manual/editor/08-imgs/7.png new file mode 100644 index 0000000..e1bafb4 Binary files /dev/null and b/docs/manual/editor/08-imgs/7.png differ diff --git a/docs/manual/editor/08-imgs/8.png b/docs/manual/editor/08-imgs/8.png new file mode 100644 index 0000000..7c7bde2 Binary files /dev/null and b/docs/manual/editor/08-imgs/8.png differ diff --git a/docs/manual/editor/08-imgs/9.png b/docs/manual/editor/08-imgs/9.png new file mode 100644 index 0000000..00fb889 Binary files /dev/null and b/docs/manual/editor/08-imgs/9.png differ diff --git a/docs/manual/editor/09-imgs/1.png b/docs/manual/editor/09-imgs/1.png new file mode 100644 index 0000000..5495136 Binary files /dev/null and b/docs/manual/editor/09-imgs/1.png differ diff --git a/docs/manual/editor/09-imgs/2.png b/docs/manual/editor/09-imgs/2.png new file mode 100644 index 0000000..a256309 Binary files /dev/null and b/docs/manual/editor/09-imgs/2.png differ diff --git a/docs/manual/editor/09-world-configuration.md b/docs/manual/editor/09-world-configuration.md new file mode 100644 index 0000000..b763246 --- /dev/null +++ b/docs/manual/editor/09-world-configuration.md @@ -0,0 +1,16 @@ +# World Configuration + +!!! note "Docs merging note" + What about moving that to export and publish. Needs new screenshots. + +You can find the Basic World Settings under the tab 'Configuration'. + +![1](09-imgs/1.png) + +*Release Date*, *Authors Name(s)*, and *Track Description* should be self explaining. + +You can also set a Thumbnail for your Track. It is shown while selecting the tracks, and while loading. So the .png file should have a high resolution such as 1920x1080 or higher. +Place the Thumbnail-File under res://Worlds/YourTrack/ as shown in the figure below: + +![2](09-imgs/2.png) + diff --git a/docs/manual/editor/10-imgs/1.png b/docs/manual/editor/10-imgs/1.png new file mode 100644 index 0000000..15e81be Binary files /dev/null and b/docs/manual/editor/10-imgs/1.png differ diff --git a/docs/manual/editor/10-imgs/2.png b/docs/manual/editor/10-imgs/2.png new file mode 100644 index 0000000..304ee4c Binary files /dev/null and b/docs/manual/editor/10-imgs/2.png differ diff --git a/docs/manual/editor/10-imgs/3.png b/docs/manual/editor/10-imgs/3.png new file mode 100644 index 0000000..b83d7cf Binary files /dev/null and b/docs/manual/editor/10-imgs/3.png differ diff --git a/docs/manual/editor/10-imgs/4.png b/docs/manual/editor/10-imgs/4.png new file mode 100644 index 0000000..88efe81 Binary files /dev/null and b/docs/manual/editor/10-imgs/4.png differ diff --git a/docs/manual/editor/10-imgs/5.png b/docs/manual/editor/10-imgs/5.png new file mode 100644 index 0000000..c133cf5 Binary files /dev/null and b/docs/manual/editor/10-imgs/5.png differ diff --git a/docs/manual/editor/10-imgs/6.png b/docs/manual/editor/10-imgs/6.png new file mode 100644 index 0000000..8741048 Binary files /dev/null and b/docs/manual/editor/10-imgs/6.png differ diff --git a/docs/manual/editor/10-scenario-setup.md b/docs/manual/editor/10-scenario-setup.md new file mode 100644 index 0000000..c6a22d7 --- /dev/null +++ b/docs/manual/editor/10-scenario-setup.md @@ -0,0 +1,71 @@ +# Scenario Setup + +!!! note "Docs merging note" + Workflows changed. Needs new Screenshots. Content and language not verified. + +In the Scenario Settings you define general thins like the time, but also the route and time table of a train. +Here you also will define NPCs. + +![1](10-imgs/1.png) + +## Scenarios +You can create as many scenarios per track as you want. But scenarios don't save any custom objects or similar things. +To edit a scenario, just simply select it from the list. + +![2](10-imgs/2.png) + +## General Settings +- Here you define the time, on which the scenarios starts. +- Also you define the maximal length of the player train. A good value is the smallest station length - 25 m. +- The Description will be shown in the beginning of the scenario +- With the scenario duration displayed in the Main Menu, the player knows, how long this scenario will gonna be +- Don't forget to save your changes with 'Save General' + +## Configuring Signals + +![3](10-imgs/3.png) + +In every scenario the signals could set to green at different ways, or behave different. +- With 'Save current Signal Data to scenario' all Signal-Data of the world will be saved to the scenario. +- With 'Load Signal Data from current Scenario' all Signal Data of the scenario will be loaded in to the world. +- With 'Reset Signal Data' Every Signal will be set to default settings + +*Attention* +You shouldn't remove or add any contact points on different scenarios. You can easily deactivate them by inserting "-" to 'By Specific Train'. (Provided that, that no train is called '-') + +![4](10-imgs/4.png) + + + +## Player Train + +![5](10-imgs/5.png) + +Please read [this](https://github.com/Libre-TrainSim/Libre-TrainSim/wiki/Testing-your-Track) article for configuring route, and start configuration. You can ignore 'Spawn Time' and 'Despawn Rail' + +**Attention**: The train is only recognized as player train, if it is named 'Player' + +### Timetable: + +![6](10-imgs/6.png) + +Now its getting funny: Here you define the timetable of the train. The order of the entries is very important, it won't be sorted at any time. +- **Node Name**: Here you define the name of the Station-Node, over which the train will drive. +- **Station Name**: Thats the name of the station how it is displayed ingame. +- **Arrival Time**: Self explaining. The fields 11, 0, 40 stands for 11:00:40 (11 am and 40 seconds) +- **Departure Time**: Also self explaining. +- **Minimal Halt Time**: Should be less or equal than Departure - Arrival. When the player arrives to late at the station, he has to hold at least the in here defined time. Unit: Seconds +- **Stop Type**: + - Do not halt: The Train Station is displayed to the player, but he doesn't have to hold there. + - Regular Stop: The default, if the player has to hold there, wait some time, and arrive + - Beginning Station: Just select this at the first entry, and only if the player spawns in this station. If for example the player starts at a railway siding, and have to drive to his first station, select 'Regular Stop' instead. + - End Station: Self explaining ;) Every Scenario should have an End Station in the end of the time table. +- **Waiting Persons**: Define how much percent of the normal people amount should wait at this station. Go for 100% at high frequented stations and lower for smaller ones. +- **Leaving Persons**: Defines, how much percent of the in the train will leave at this station. It's a bit random. +- **Arrival Announce Path**: Path of a sound file. Will be played when train arrives at a station. Example: `res://Resources/Basic/Sounds/platform_endstation.ogg` +- **Departure Announce Path**: Path of a sound file. Will be played when train leaves at a station. Example: `res://Resources/Basic/Sounds/platform_departure.ogg` +- **Approach Announce Path**: Path of a sound file. Will be played before the train arrives at a station. Example: `res://Resources/Tutorials/Sounds/next_station_tutorialbach.ogg` + +*(If you want recorded some station names by the speaker, just write to Jean28518)* + +Don't forget to click on 'Save Train' in the end. \ No newline at end of file diff --git a/docs/manual/editor/11-imgs/1.png b/docs/manual/editor/11-imgs/1.png new file mode 100644 index 0000000..0d15673 Binary files /dev/null and b/docs/manual/editor/11-imgs/1.png differ diff --git a/docs/manual/editor/11-imgs/2.png b/docs/manual/editor/11-imgs/2.png new file mode 100644 index 0000000..9f02316 Binary files /dev/null and b/docs/manual/editor/11-imgs/2.png differ diff --git a/docs/manual/editor/11-imgs/3.png b/docs/manual/editor/11-imgs/3.png new file mode 100644 index 0000000..b82801e Binary files /dev/null and b/docs/manual/editor/11-imgs/3.png differ diff --git a/docs/manual/editor/11-npc-trains.md b/docs/manual/editor/11-npc-trains.md new file mode 100644 index 0000000..d3d89cc --- /dev/null +++ b/docs/manual/editor/11-npc-trains.md @@ -0,0 +1,47 @@ +# Setup of NPC Trains + +!!! note "Docs merging note" + Falls together with the previous article. Since the workflow changed, I imagine they don't longer need to be seperate articles if the system spawns trains automatically. + + Screenshot outdated. Language and content not verified. + +NPC trains are configured per scenario. Make sure to read [this article](10-scenario-setup.md) before adding any NPC train. + +**The npc trains are defined only for driving at the track! This should not used, if the train has only to stand somewhere the whole time.** + +## Adding new NPC train +For that define a name for the NPC train, and click on 'New'. +But you could also click on 'Duplicate' if you want, so you may not add a whole timetable or route. + +![1](11-imgs/1.png) + +## Settings +If you see, the settings are very similar to the settings of the player train. +The Train drives as a player would drive it. With stations, signals, timetable, and so on. +So you should configure them too. +But following variables are gonna be used by the npc train: +- **Spawn Time**: You have to configure this variable. It defines the the time, when the player npc should be created. So for example if your scenario starts at 11:00 am, its no problem, that a npc train is created at 11:10 am. 13 35 12 stands for 1:35 pm and 12 seconds. +The train will spawn at his start rail with the defined parameters as *Direction*, *Start Rail Position*, and *Door Configuration at Start*. +- **Despawn Rail**: If you want, that the npc train despawns, at a specific point, just insert here the name of the given rail. As the train touches this 'Despawn Rail', it will be removed from the world. Make sure, that the train reaches the Despawn Rail via the Route. + +## Example: + +![2](11-imgs/2.png) + +I want a train which drives in to a station, will halt, open the doors, departs, and despawns at a rail (green line in figure above). +1. First I create a new train, and define the route. +2. Second I define the Start Position with Direction, and in my case the doors at the beginning are closed. +3. Then I define the Spawn time. The player will halt at 11:00:40, and depart at 11:01:00 at the opposite rail. So I define as Spawn Time. 10:59:15 pm +4. Then I define the Despawn Rail (Where the green X is) +5. Now I define the timetable of the train. I want only to halt at Röthenbach2 for some time until 11:00:30, and want to drive him further on. The Arrival Time at npc trains could be ignored. +6. **I click on 'Save Train'** + +![3](11-imgs/3.png) + +7. Now I configure the signals, over which the train will drive. (With pressing 'Load Signal Data form current Scenario' before and pressing 'Save current Signal Data to scenario' after. +8. Test it out! If there are any problems, you can fly around in the scene by pressing 0 Ingame. + + + + + diff --git a/docs/manual/editor/12-export-and-publish.md b/docs/manual/editor/12-export-and-publish.md new file mode 100644 index 0000000..4faa86f --- /dev/null +++ b/docs/manual/editor/12-export-and-publish.md @@ -0,0 +1,81 @@ +# Export and Publish + +!!! note "Docs merging note" + New workflow, too. Also let's replace the Google Form with a GH Link to a new repo in preparation for a mod portal. + + Content and language not verified. + +So if your complete track is finished, let's export it! + +**Please save and unload all chunks in the 'World Configuration' Tab before exporting!** + +## Exporting Track + +Select 'Project' -> 'Export...'. + +![1](12-imgs/1.png) + +As seen below I don't have any export template downloaded. If this message shows up, click on 'Manage Export Templates', and download the appropriate export template. That cloud take a lot time. + +![2](12-imgs/2.png) + +After that you have to reopen 'Project' -> 'Export...'. Then add a new Template as seen below. + +![3](12-imgs/3.png) + +Give it an appropriate name. + +Now define in the tab 'Resources': +- Export Mode: 'Export selected resources and dependencies' + - Select in the window below `/Worlds/YourTrackName` + - Select `Resources/YourTrackName` + - ... +- Now you should define some non-resource files/folders: `Worlds/YourTrackName/YourTrackName.save, Worlds/YourTrackName/YourTrackName-scenarios.cfg` *(Filenames changed since version 0.8!)* + +In the end it should look like this: + +![4](12-imgs/track_export_presets.png) + +Now click on `Export PCK/Zip` at the bottom of the window, select any folder (for example your own Downloads folder), and name it YourTrackName.pck. + +**WARNING: It is very important that your TrackName is everywhere exact the same! If not, Libre TrainSim won't recognize it in the end.** + +If it looks similar to the figure below, click 'Save' in the end. + +![5](12-imgs/5.png) + +After few seconds the export is finished, and you can test your packed track out in the real Libre TrainSim! + +## Licensing + +It is recommended to add a license file to your work. Its completely up to you which license to take + +If you don't mind licenses, take [CC0](https://creativecommons.org/publicdomain/zero/1.0/). This License says: Everyone could do everything with it without any restrictions. + +If you want to be named as original author, and want, that modified tracks should be released under the same license, choose: [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/) + +So create next to the .pck file a simple file named `LICENSE` and add for example following lines: +``` +Track and Assets released under: CC0 (https://creativecommons.org/publicdomain/zero/1.0/) +Author: YOUR NAME +E-Mail: YOUR_E-MAIL_(Optional) +Source: libre-trainsim.de +``` +*Of course you can design your LICENSE file as you want, it's your work! (Don't mind the Basic resources, they are released under CC0). But it is important to have a LICENSE file, because without it you can't upload it to libre-trainsim.de* + +## Saving source files and packing upload file + +So before uploading your track you should pack a source.zip file. In it there should be all files, you needed to create the track. (.png, .blend, .obj, .xcf, .gd, .tscn, .....). They are very important: If for example your track gets outdated, and someone want to update your track to the newest version, he will need the files in source.zip. With source.zip your track could live in etnerity ;) + +Example of a source.zip file: + +![6](12-imgs/6.png) + +## Uploading + +So in the end you should have these files: + +![7](12-imgs/7.png) + +Pack them to a zip-file, and upload them here: https://docs.google.com/forms/d/e/1FAIpQLSfWEB3gWOnqp9AoOlpxoZ2IdnbpTCr35xgMQSVgl9KEC0tiHw/viewform?usp=sf_link + diff --git a/docs/manual/editor/12-imgs/1.png b/docs/manual/editor/12-imgs/1.png new file mode 100644 index 0000000..fc00808 Binary files /dev/null and b/docs/manual/editor/12-imgs/1.png differ diff --git a/docs/manual/editor/12-imgs/2.png b/docs/manual/editor/12-imgs/2.png new file mode 100644 index 0000000..262011a Binary files /dev/null and b/docs/manual/editor/12-imgs/2.png differ diff --git a/docs/manual/editor/12-imgs/3.png b/docs/manual/editor/12-imgs/3.png new file mode 100644 index 0000000..d7327a5 Binary files /dev/null and b/docs/manual/editor/12-imgs/3.png differ diff --git a/docs/manual/editor/12-imgs/5.png b/docs/manual/editor/12-imgs/5.png new file mode 100644 index 0000000..933431f Binary files /dev/null and b/docs/manual/editor/12-imgs/5.png differ diff --git a/docs/manual/editor/12-imgs/6.png b/docs/manual/editor/12-imgs/6.png new file mode 100644 index 0000000..83017b8 Binary files /dev/null and b/docs/manual/editor/12-imgs/6.png differ diff --git a/docs/manual/editor/12-imgs/7.png b/docs/manual/editor/12-imgs/7.png new file mode 100644 index 0000000..c15926b Binary files /dev/null and b/docs/manual/editor/12-imgs/7.png differ diff --git a/docs/manual/editor/12-imgs/track_export_presets.png b/docs/manual/editor/12-imgs/track_export_presets.png new file mode 100644 index 0000000..c30693d Binary files /dev/null and b/docs/manual/editor/12-imgs/track_export_presets.png differ diff --git a/docs/manual/editor/index.md b/docs/manual/editor/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/manual/editor/new-tutorial.md b/docs/manual/editor/new-tutorial.md new file mode 100644 index 0000000..cd6be94 --- /dev/null +++ b/docs/manual/editor/new-tutorial.md @@ -0,0 +1,34 @@ +# A new tutorial + +The old tutorial doesn't teach well and is hard to improve. +Let's try a newly structured one. + +**This is a step by step tutorial for the editor!** +The modding section should get a step by step tutorial, too. Additionally, we should aim to provide a reference style manual that showcases single features and their use cases when being looked up. + +Concepts should be introduced in a recurring pattern so they are easily understandable throughout the manual. New terms should be explained. These explanations should be collected in a single page. + +# Mod or Editor? +When should I use a mod, when the editor +# Building Tracks +## Switches +# Creating stations +# Creating a scenario +# Testing the map +# Adding objects to the map +## "normal" objects +## Track objects +## Cheating perf by using invisible tracks +If they still exist +## Map configuration +## Adding station names and announcements +## More scenarios +## Exporting + +For mods (for the editor): +# Setup +# Setup of the ingame editor +# Asset creation +## Objects +## Trains +## Humans \ No newline at end of file diff --git a/docs/manual/index.md b/docs/manual/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/manual/mods/index.md b/docs/manual/mods/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/manual/play/index.md b/docs/manual/play/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/mods/custom-world-scripts.md b/docs/mods/custom-world-scripts.md new file mode 100644 index 0000000..2f45181 --- /dev/null +++ b/docs/mods/custom-world-scripts.md @@ -0,0 +1,211 @@ +# Custom World Scripts + +!!! danger + This page is considered legacy. We will keep it around as a reference for this release but please do not rely on the information or the continued support. If you are interested in scenarios, please [help us drafting a new system](https://github.com/Libre-TrainSim/Libre-TrainSim/issues/new). + +It is also possible to add some custom code, like used at tutorials. It is a bit hacky, but the concept is very simple. This can be very powerful. + +For that you need some basics in GDScript, what you will unterstand in 5 minutes, if you have a bit programming experience, it's similar to python. Read [this article](https://docs.godotengine.org/en/stable/getting_started/scripting/gdscript/gdscript_basics.html) for that. + +## Adding Script + +First of all: The script itself is not scenario specific, but it can check itself, which scenario is currently running.. So let's add a script. Select the 'World' Node with right click, and select 'Add Child Node': + +![1](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/1.png) + +Now just select 'Node', and select create. + +![2](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/2.png) + +By double clicking the new node (its at the bottom) you can rename it whatever you want. In the end it should look like this: + +![3](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/3.png) + +If you want you could add your own complete custom script, but a template is very useful. In the 'File System' tab navigate to `res://addons/Libre_Train_Sim_Editor/Data/Scripts/` rightclick `CustomScenarioTemplate.gd`, and select duplicate. Move then the duplicate to `res://Worlds/YOURWORLD`. In the end it should look like this: + +![4](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/4.png) + +Now drag and drop your `CustomScript.gd` from the 'FileSystem' tab to your new Script node in the 'Scene' tab: + +![5](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/5.png) + +In the end you should see a script symbol next to your new script node. Just click on it, and the editor should open automatically. + +![6](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/6.png) + +## Editing Script + +For better editing press the fullscreen button of the main window: + +![7](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CustomScripts/7.png) + +Dont forget to save by pressing `Ctrl + S`. + +### Header + +```gdscript +extends Node + +onready var world = find_parent("World") +onready var player = world.get_node("Players/Player") +``` + +This code you will find at almost every component of modules from Libre TrainSim. These are the main components. + +- The world node handles such components as chunk system, time, spawning other trains, scenario, etc. Also every single component like rails, trees, trains, signals, stations, etc. can be accessed via it. For example if I want to reference a signal then I write `var signal = world.get_node("Signals/SIGNALNAME")`. For scripting just further one variable is interesting: `world.time`. `world.time[0]` contains the hour, `world.time[1]` contains the minute, `world.time[2]` contains the second. +- The player node is simply the player. It's the train, which the player drives. It drives over rails, handles the ingame HUD, messages, and stores much information like the timetable, speed, doors, ... You can find the player script for looking after variables under `res://addons/Libre_Train_Sim_Editor/Data/Scripts/Player.gd`. Only the first 100 lines should be interesting to you. + +**BUT IT IS HIGHLY RECOMMENDED TO NOT CHANGE ANY OF THESE VARIABLES VIA SCRIPT, IF YOU DON'T NEED TO!** The game couldn't work correctly after it. + +- Some functions from [jTools](https://github.com/Jean28518/Godot-jTools) could be useful too. jTools is already integrated to Libre TrainSim. jAudioManager and jEssentials could be interesting for custom scripts. + +### Stuff for specific scenarios + +```gdscript +var message = "" +var step = 0 +var scenario = Root.currentScenario +func _process(delta): + internal_stuff(delta) + + +func next_step(): + # ... + step += 1 + #.... + +func internal_stuff(delta): + #.... + +``` + +This handles the basic functionality. + +So now let's add a function, which will handle one specific scenario from step to step. +At first we to create a function: + +```gdscript +func scenario1(): + pass +``` + +(You can remove `pass`, when you added something to the function). Now you need to call the function in `_process(delta)`: + +```gdscript +func _process(delta): + internal_stuff(delta) + if scenario == "ExactNameOfTheScenario": + scenario1() +``` + +Now the function is just called, if the player plays a specific scenario. *(For advanced scripting: Keep in mind, that the function is called every game cylce (about 60 times per second)* + +Now because of `internal_stuff()` some magic happens, and the code below will work like written in the comments: + +```gdscript +func scenario1(): +match step: + 0: + message = "Welcome! Please rise up the pantograph by pressing b" ## In Beginning of every step, you should define next message. + if player.pantograph: # condition, if step 0 is done + next_step() # move on to next step + 1: + message = "Great! To close the Doors, press 'o'.\n\nWhith 'i' you can open the left one,\nwith 'p' you open the right door." + if not (player.doorRight or player.doorLeft): + next_step() + 2: + message = "Last message of custom scenario. Thanks for playing!" +``` + +So happy coding! + +*** + +For example here is the code of the mobile tutorial function: + +```gdscript +func basics_mobile_version(): + match step: + 0: +# message = "Welcome to Libre TrainSim!\nPlease have in mind that this is an early alpha version, in which many features are missing, and some bugs are possible.\nThe mode is now set to Easy.\n\nLet's start the engines!\nPress 'b' to set up the pantograph and wait a bit.\nAfter 5 sconds you can press 'e' to start the engines!" + message = TranslationServer.translate("TUTORIAL_4_0") + player.get_node("HUD/MobileHUD/Pantograph").modulate = Color(1, 0.5, 0, 1) + if player.pantograph: + next_step() + 1: + # message = Press e to start engines + player.get_node("HUD/MobileHUD/Pantograph").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/Engine").modulate = Color(1, 0.5, 0, 1) + message = TranslationServer.translate("TUTORIAL_4_1") + if player.engine: + next_step() + 2: +# message = Our departure is at 12:00. Let's wait for the depart message in the bottom left corner." + message = TranslationServer.translate("TUTORIAL_4_2") + player.get_node("HUD/MobileHUD/Engine").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/Camera").modulate = Color(1, 0.5, 0, 1) + if player.currentStationName == "": + next_step() + 3: +# message = "Great! To close the Doors, press 'o'.\n\nWhith 'i' you can open the left one,\nwith 'p' you open the right door." + message = TranslationServer.translate("TUTORIAL_4_3") + player.get_node("HUD/MobileHUD/Camera").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/DoorClose").modulate = Color(1, 0.5, 0, 1) + if not (player.doorRight or player.doorLeft): + next_step() + 4: +# message = "Let’s abort! Use the arrow keys to drive. \n\n\tPress the up arrow key to accelerate / release the brakes.\n\tPress the down arrow key to release acceleration / apply the brakes. \n\nHint: You can see your current command at the right tachometer." + message = TranslationServer.translate("TUTORIAL_4_4") + player.get_node("HUD/MobileHUD/DoorClose").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/Up").modulate = Color(1, 0.5, 0, 1) + player.get_node("HUD/MobileHUD/Down").modulate = Color(1, 0.5, 0, 1) + if Math.speedToKmH(player.speed) > 20: + next_step() + + 5: +# message = "Ahead you see an orange signal. That means that the next signal is going to be red. So make sure, you apply the brakes that you will stand before the red signal.\n\nWith the left arrow key you can easily set acceleration and brakes to zero. Try it, if you have brakes or accleration applied!" + message = TranslationServer.translate("TUTORIAL_4_5") + player.get_node("HUD/MobileHUD/Up").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/Down").modulate = Color(1, 0.5, 0, 1) + if Math.speedToKmH(player.speed) == 0 and not player.overrunRedSignal: + world.get_node("Signals/Signal2").status = 1 + next_step() + 6: +# message = "Great... \nWait... the signal is now green! Now we need to accelerate very fast.\nTo do this, simply press the right arrow key. It instantly sets the train to max power." + message = TranslationServer.translate("TUTORIAL_4_6") + player.get_node("HUD/MobileHUD/Down").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/Up").modulate = Color(1, 0.5, 0, 1) + if player.distanceOnRail > 700 and player.currentRail.name == "Rail": + next_step() + 7: + player.get_node("HUD/MobileHUD/Up").modulate = Color(1, 1, 1, 1) +# message = "The signal in front of you is blinking.. what does this mean?\nIf a signal is blinking, then its announcing a new speed limit, which is lower than your current one.\nNo fear, the blinking signal just announce it, the speed limit will become effective at the signal behind it.\n\nIf e.g. the signal displays a 8, then the speed limit is 80 km/h.\nOrange signs/digits are always announcing limits,\nWhite signs/digits will set the speed limit effective." + message = TranslationServer.translate("TUTORIAL_4_7") + if player.currentRail.name == "Rail2": + next_step() + 8: +# message = "In 600 meters there will be the next train station. Every station is announced in the left bottom corner, if its 1000m away. Certainly you already saw it.\n\nIt is recommended to brake down to about 70 or 60 km/h, and then brake softly if you are shortly before the train station.\nLets arrive!" + message = TranslationServer.translate("TUTORIAL_4_8") + if player.distanceOnRail > 250 and player.currentRail.name == "Rail2": + next_step() + + 9: + # message: Hint: If you don't know further on at any time or you just want to enjoy the ride, press 'ctr' + 'a' to activate the autopilot. + message = TranslationServer.translate("TUTORIAL_4_9") + player.get_node("HUD/MobileHUD/Autopilot").modulate = Color(1, 0.5, 0, 1) + if player.speed == 0 and player.currentStationName == "Tutorialbach" and not player.wholeTrainNotInStation: + next_step() + + 10: +# message = "Great, you arrived securly!\nNow you have to open the doors.\nWith 'i' you can open the left one, with 'p' the right one.\nIn our case we have to open the left one with 'i'." + message = TranslationServer.translate("TUTORIAL_4_10") + player.get_node("HUD/MobileHUD/Autopilot").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/DoorLeft").modulate = Color(1, 0.5, 0, 1) + if player.isInStation: + next_step() + 11: +# message = "Thank you for playing! You can now exit the game with 'Esc'" + message = TranslationServer.translate("TUTORIAL_4_11") + player.get_node("HUD/MobileHUD/DoorLeft").modulate = Color(1, 1, 1, 1) + player.get_node("HUD/MobileHUD/PauseButton").modulate = Color(1, 0.5, 0, 1) +``` diff --git a/docs/mods/import-pipeline.md b/docs/mods/import-pipeline.md new file mode 100644 index 0000000..4f03263 --- /dev/null +++ b/docs/mods/import-pipeline.md @@ -0,0 +1,47 @@ +# Import pipeline + +This page introduces the import pipeline for LTS. It'll explain supported content, file strucutre, assets, and licensing. + +## Supported content + + 1. 3D Objects (from landscape to bins to trains) + 2. Sound files + +!!! warning + Level of Detail is currently not supported out of the box. + +!!! tip "Good practices" + - Prefer glTF as your primary export format. + - Use as much topology as required and as little as possible. If you are new to 3D modelling search for tutorials and guides that show *game-ready* workflows. A good chunk of videos on YouTube for Blender is made for *offline rendering, eg. film or artwork renders*. If the tutorial uses loop cuts to control the beveling of an edge, it's not probably not game-ready. + - Use proper scaling. One unit in Blender and Godot is one metre. In Maya, one unit is ten centimetres. The object should have a scale of one in Godot. + +## File Structure + +Always keep your source assets as close as possible to the scene. If you are importing for use as rail attachments, you need to save the meshes in a dedicated folder. + +## Lighting + +When using glTF (or FBX by all means) lights can be created in your 3D content creation software. However lighting is not only a realistic component but also an artistic one. You should strive to use as few lights as possible but as many as required. + +!!! tip + Have a look at lighting in games and how lights work to guide attention. These are classic level design problems. As we don't have any level designer right now, you are probably better of researching the topic on your own. + +## Materials + +For more information take a look [at the offical Godot documentation.](https://docs.godotengine.org/en/3.5/tutorials/3d/spatial_material.html). +You want to use something like Substance Painter, Material Maker, or any other alternative you can find. Good materials go a long way in visual quality. + +!!! tip + You can read more about texel density if you are interested in the proper texture sizes. Also use channel packing to combine AO, roughness, and metallness maps to save VRAM. + +## Objects + +It's perfectly valid to start with existing objects and modify them to get to a coherent visual style. Please make sure you're complying with licenses. + +## Licensing + +FOSS lives and breathes through sharable and open content. Thus, please ensure to properly credit the external content you used and share your content under a open license. Have a look at [Choose a license](https://choosealicense.com/) and [Creative Commons](https://creativecommons.org/licenses/) respectively. + +If you want to allow anyone do do about anything with your content, then [Creative Commons 0](https://creativecommons.org/share-your-work/public-domain/cc0/) is the right license for you. Most assets in the base game are licensed CC0. + +### YouTube-Video: [Click Here](https://youtu.be/qZrul1Gagv8) diff --git a/docs/mods/setup-imgs/config.jpg b/docs/mods/setup-imgs/config.jpg new file mode 100644 index 0000000..ec59331 Binary files /dev/null and b/docs/mods/setup-imgs/config.jpg differ diff --git a/docs/mods/setup.md b/docs/mods/setup.md new file mode 100644 index 0000000..cf96051 --- /dev/null +++ b/docs/mods/setup.md @@ -0,0 +1,69 @@ +# Setup + +!!! warning "Docs merging note" + We need to update the help link in the LTS modding tools to point to this docs or update the webpage. + +This page should inform you how to get started with LTS modding. +You will learn about mod creation, setup of the editor, getting the source, and exporting the mod. + +## Getting the source + +Libre Train Sim is available as [git repository](https://git-scm.com). You can either download the source of the latest release or clone the release branch. Cloning the release branch enables you to use git to update your LTS source in the future. While downloading the release source is easier, cloning the repository is easier to update when updates for the version are released. + +## Downloading the release source + +1. [Find the target version](https://github.com/Libre-TrainSim/Libre-TrainSim/releases) +2. Open assets and download the source code. + +### Cloning the code + +!!! warning + If you plan to version your changes, you should fork LTS first, clone your fork and checkout then. Follow the [pull request workflow instructions to learn more](/contribute/getting-started.md). The important bit of this section is the branch naming pattern used to distinguish release branches. It is `release/`. + +1. Ensure you have [git](https://git-scm.com) installed. +2. Open a shell in your target directory. On Windows you can press `Shift+RMB` to find a new entry called something along the lines: `Open terminal here` or `Open powershell here` or `Open command prompt here`. +3. Enter `git clone https://github.com/Libre-TrainSim/Libre-TrainSim/ lts` to clone the repository into the lts folder. +4. Switch to the lts folder `cd lts`. +5. Checkout the the target release branches. These branches are prefixed with `release/`. In order to get the 0.9 release source, type `git checkout release/0.9` + +### Download and setup Godot + +Before you can do anything meaningful with the code, you need to have Godot installed. Godot is the game engine that powers LTS. You can either [download Godot](https://godotengine.org/download/3.x/) or you install Godot using your package manager of choice. **Make sure to use Godot 3!** On Windows [scoop](https://scoop.sh) is viable choice. + +If you are familiar with your command line and have set up Godot in your `PATH`, use `godot . -e` in the `lts/src` folder. Otherwise open Godot, select `Import Project` and select `lts/src`. + +## Mod creation + +Find the LTS Modding Tools panel. By default, it is be located as a tab next to the file system. Press `Create a new mod`. The new mod will be created in `res://mods/`. + +Mods have a config file named `content.tres`. This file will be exported as a seperate file next to the pack. It is used to get information about the content pack before loading it. The names are populated with the data entered in the creation menu. You can also set the mod version in this file and other mods your mod is depending on. The version will be used to check if the depencies are satisfied. + +![Screenshot of the config.tres resource of Libre Train Sim](setup-imgs/config.jpg) + +There are couple of folders that can be configured. + + * `Environment Folders` - no use? + * `Material Folders` - Use only for materials that are used for rail attachments. Please note that proper textures are specific to the mesh (UV map). Reusing materials by not creating UV maps will result in bad visuals. Only necessary for materials that should appear in the ingame editor. + * `Music Folders` - no use? + * `Object Folders` - Has dual use for finding object groups (these will be queried for the actual scenes so your objects can have any folder structure you may like.) and the mesh files used for rail attachments. Only necessary for objects that should appear in the ingame editor. + * `Persons Folders` - no use? May simply spawn other people? + * `Rail Type Folders` - no use? May add more rails (these need to be changed for each visual instance in the editor) + * `Signal Type Folders` - no use? + * `Sound Folders` Only necessary if sound files need to be selectable in the ingame editor. + * `Texture Folders` - no use + +!!! danger + We should remove unused folders! + +Lastely trains and worlds are referenced. Resource references are saved in the train and world files. + +## Mod export + +Find the mod tools and press `Export a mod`. Select the folder of the mod you want to export. The mod will be exported to the addons directory. To distribute the mod, you need to share the whole mod folder. + +## Testing mods in editor builds + +Godot can't reliably load pack files when it operates as editor. As a consequence we disabled mod loading at run-time for these builds. To test your mod, you need to append the folders, trains, and worlds to the LTS `res://content.tres`. Doing so effectively makes your mod base game but as long as you don't have dependencies (on packed mods) there is no issue. + +!!! note + It would be nice to do that automatically for mods in source mode though. diff --git a/docs/mods/train-creation.md b/docs/mods/train-creation.md new file mode 100644 index 0000000..5bd4c1f --- /dev/null +++ b/docs/mods/train-creation.md @@ -0,0 +1,74 @@ +# Train Creation + +!!! note "Docs merging note" + Content and language not verified. Screenshots, assets and links need updating. Also someone should verify the info and try creating a new train. + +**Attention: This topic is very complex, you need some basic programming skills. Also basic knowledge about the Godot Engine is required. It is recommended, to get in touch to Libre TrainSim first while building a track.** + +You can download an example [here](https://www.server-jean.de/LibreTrainSim/JFR-1.zip). +We won't do a step by step tutorial, because every train works differntly, and has other features. + +## General: +A train is handled in a normal single .tscn file (=a single scene). It cointains 3D Models an lights of every wagon, the basic funtionality, and specific scripting. Because of its 'raw' implementation it is possible to add e.g. complete new security systems, and much more. So modding is 'very easy'. + +All files can be stored in a single folder. It is very important to download and set up the Editor. -> You can look in [this article](https://github.com/Libre-TrainSim/Libre-TrainSim/wiki/Getting-Started,-Preparing-your-World) if you don't know how to do. Under "Trains" you can then create a new folder. In there create a new scene, which save name is equal to the name, how the Train-Name is displayed in LibreTrainSim Menu. For example: `ICE4.tscn`. + +If you don't understand something feel free to explore, and modify the example above. Of course it's okay to reuse some files of the example for your own train! + +LODs are currently not supported. + +## Essential Setup: +- The Root-Node of the Train (Train.tscn) should be a Spatial (3D) Scene, and be named `Player`. It should have attached the following script: `res://addons/Libre_Train_Sim_Editor/Data/Scripts/Player.gd`. NEVER CHANGE THIS SCRIPT! +- A Camera Node (Type Camera (3D)) called `Camera`. The Camera should be positioned correctly in the Cabin. +- A Spatial (3D) Node called `Cabin`. In it there should be everything you see from the drivers stand. (Displays, Brake/Acceleration Rolls, etc.). Please make sure that the 3D Stuff is at the "real" position compared to the outer view. Of the wagon node. Usually this position is not at (0,0,0). *Example: The Cabin of the JFR-1 is at (5.3,0,0)* +- One or more "Wagon-Nodes" (3D/Spatial Node). With following script attached: `res://addons/Libre_Train_Sim_Editor/Data/Scripts/Wagon.gd`. In it there should be the 3D Object of the outerview of the wagon. *If a wagon should have movable doors: Two AnimationPlayers should be attached. The first one called `DoorRight` and the second one `DoorLeft`. Every door has to be added as single 3D Object and should be placed at the correct position of the wagon* These wagons are only shown, if you see the train from the outside. +- A Sound Node: (Simple 3D/Spatial Node) called `Sound`. Under it every possible sound (AudioStreamPlayer3D) should be attached. **Because every train has other "sound types" the sounds have to be programmed completely by you.** You could attach this custom script to the sound node. Read the sound section below for more informations +- A FrontLight Node: (Simple 3D/Spatial Node) called `FrontLight`. Should be self explaining. In it there should be attached two spot lights. Here are some default-settings: ![1](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CreatingTrains/1.png) They should be "turned on" in the scene. +- A CabinLight Node: (Simple 3D/Spatial Node) called `CabinLight`. Works like the the FrontLightNode. Please remind that this is only for the drivers-stand. + +**The Problem with the lights** Because of limitations from Godot Libre TrainSim doesn't support Lights for the passenger rooms. With Godot 4.0 this will be fixed. + +## Train Attributes: +All important settings can be set at the `Player` Node in the Inspector. Here you find very many variables: ![2](https://raw.githubusercontent.com/Jean28518/Libre-TrainSim/master/Documentation/Images/CreatingTrains/2.png) + +- **Acceleration**: Acceleration of the train in m/(s^2). (Applied at 100% Acceleration) +- **Brake Acceleration**: Like Acceleration but for the brakes. Self explaining. Unit: m/(s^2) +- **Friction**: Self explaining. Per second the speed is multiplied by (1-Friction). Example at Friction = 0.005: 100km/h -(after 1 Second)-> 100 km/h * (1-0.005) = 99.5 km/h +- **Length**: Describes the length of the whole train. +- **Speed Limit**: Maximum speed, to it the player can technically accelerate. +- **Control Type**: + - 0: The 'simple' assignement: You can only control the train with the arrow keys, even you didn't chose 'Easy Mode' before playing. + - 1: If the player deselected 'Easy Mode' before playing: He will be able to drive via "WASD", so a separated Brake and Acceleration Roll is simulated. Just choose this mode, if your train really has separate Brake, ans sparate Acceleration. +- **Electric**: The Train is an electric one. In the beginning of the scenario you have to press B to rise the pantograph. +- **Pantograph Time**: describes how long it does take, to rise the pantograph. Unit: seconds +- **Doors**: If checked, the Train will have the ability to open and close doors. +- **Doors Closing Time**: Self explaining.. Unit in seconds. +- **Braking Speed**: Describes the value, how much percent Brakes could be applied in a second. 0.3 is 30%. +- **Brake Release Speed**: Describes the value, how much percent Brakes could be released in a second. +- **Acceleration Speed**: Describes the value, how much percent Acceleration could be applied in a second. +- **Acceleration Release Speed**: Describes the value, how much percent Acceleration could be released in a second. +- **SiFa Enabled**: If the enabled, and player deselected *Easy Mode*, then he has to press `Space` every 30 seconds. +- **Desciption**: Description, which is displayed, when selecting the train in Main-Menu. With `\n` you can make a new line. +- **Author, Release Date**: Self explaining.. +- **Screenshot Path**: Path to a nice picture of the train. It will be shown in the Main Menu, if train selected. The picture should be .png and inside your trains folder. Example: `res://Trains/JFR1/JFR1-White.png` +- **Wagons**: In here you define the composition of the train. In there some wagon nodes should be defined. Of course the same wagon can be assigned multiple in this array. +- **Wagon Distance**: The distance between the wagons. Unit: meter +- **Camera Factor**: Describes, how strong the camera in the cabin moves when accelerating or braking. + +## Technical Background: +The whole train will be loaded in the world while spawing. If it is a NPC, then such nodes as Camera, HUD, and the Cabin are removed. +The Train has two main parts: +1. The 'Brain', or the Heart: The Player Node itself: It handles the player Input, the speed, the route, stations, signals and so on. How already above described you NEVER should change this. It will be updated over time automaticley, and will have the newest features in the next versions, if it is possible. *This part is next to the 'World' Node the essential of LibreTrainSim.* +2. If a train can be seen by a player, the wagons are rendered. They are only 'decoration', and are making the train imaginable ;) They handle such things as the visual, and the (something) audible, or the visuals of the pantograph. Because every train is different, they can be controlled via a *Specific Script*, wich interacts as an interface between the Player Node, and the Wagons. But the wagons also have their own script (which you shouldn't change), and drive in dependence of the Player Node on the rails. + +## Tips: +- Start with a very simple train. -> Simple Object, single wagon, very simple driver cabin. Then expand your train functions further on. +- Try to play with some other trains: Look what changes, if you adjust some variables or swap some objects,... +- Try to use as few lights as possible +- To loop a Sound it should be in .ogg format. +- The sound is not good implemented in 0.7. In 0.8 that will gonna be better.. +- Feel free to read the code of player.gd or the specific script in the example. They could help a lot +- If you have questions, feel free to ask here: https://libre-trainsim.de/community + +## Helpful articles: +- Animation: https://www.youtube.com/watch?v=18Em80Bfjp4 diff --git a/mkdocs.yml b/mkdocs.yml index eef37f3..5f9dbec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,30 @@ -site_name: Libre Train Sim documentation +# Project information +site_name: Libre TrainSim documentation +site_description: Documentation for Libre TrainSim +site_author: Libre TrainSim documentation contributers +site_url: https://libretrainsim.org/ + +# Repository information +repo_name: lts-docs +repo_url: https://github.com/Libre-TrainSim/lts-docs/ + theme: - name: readthedocs #'rtd-dropdown' + name: readthedocs + collapse_navigation: false + plugins: - search + - awesome-pages: + collapse_single_pages: true + +# We need some special navigation overrides to clean the sidebar up a little bit. +# Refer to https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin for an overview of the available features. + +nav: + - Home: index.md + - ... + # Cheatsheet: https://stephane-cheatsheets.readthedocs.io/en/latest/misc/readthedocs_mkdocs/ diff --git a/requirements.txt b/requirements.txt index 2c7787a..97a32cb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ -mkdocs==1.2.3 -pymdown-extensions==9.2 -mkdocs-awesome-pages-plugin==2.7.0 \ No newline at end of file +mkdocs==1.3.0 +pymdown-extensions==9.5 +mkdocs-awesome-pages-plugin==2.7.0 +jinja2<3.1.2 \ No newline at end of file