diff --git a/README.md b/README.md index bab04fe7..4fbecb81 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,236 @@ + + [![Build status](https://ci.appveyor.com/api/projects/status/ouns27vystoasiwx?svg=true)](https://ci.appveyor.com/project/Milek7/maszyna-8kwj6/branch/master) -# [MaSzyna Train Simulator](https://eu07.pl/?setlang=en) -MaSzyna is a free, polish train simulator. MaSzyna executable source code is licensed under [MPL 2.0 license](https://www.mozilla.org/en-US/MPL/2.0/), and comes with huge pack of free assets, on [custom license](https://eu07.pl/theme/Maszyna/dokumentacja/inne/readme_pliki/en-licence.html). -# Getting Started -## Prerequisites -List of requirements for compiling executable. For usage/runtime requirements [see here](#minimum-requirements). +# MaSzyna Train Simulator -*In brackets there are oldest tested versions.* +_A free, **Polish** train simulator._ -### **1. Software:** -- [CMake](https://cmake.org/) (3.0) -- [make](https://www.gnu.org/software/make/) -- Compiler supporting C++14*. Tested under: - - Visual Studio (2017) - - GCC (8.2.1) +[Website](https://eu07.pl/?setlang=en) · [Report an issue](https://github.com/eu07/maszyna/issues) · [Dev chat](https://milek7.pl:8065/eu07/channels/dev) - **Note:** MinGW is not supported now. There were some issues with it. - - **\* technically, in source code we have some features from C++17, but even older compilers should handle that. You were warned.** +MaSzyna executable source code is licensed under the [MPL 2.0](https://www.mozilla.org/en-US/MPL/2.0/) and comes with a large pack of free assets under a [custom license](https://eu07.pl/theme/Maszyna/dokumentacja/inne/readme_pliki/en-licence.html). -### **2. Dynamic libraries:** -- [GLFW 3.x](https://www.glfw.org/) (3.2.1) +## Table of Contents - **Note:** There's some issue in our build system. If link error occurs, use `-DGLFW3_LIBRARIES=''` in CMake. -- [GLM](https://glm.g-truc.net/) (0.9.9.0) -- [serialport](https://sigrok.org/wiki/Libserialport) (0.1.1) -- [sndfile](https://github.com/erikd/libsndfile) (1.0.28) -- [LuajIT](http://luajit.org) (2.0.5) -- [GLEW](http://glew.sourceforge.net) (2.1.0) -- [PNG](http://www.libpng.org/pub/png/libpng.html) (1.6.34) -- [OpenAL](https://www.openal.org) (1.18.2) -- pthread -- [Python 2.7](https://www.python.org) -- [asio](https://think-async.com/Asio) (1.12) - -### **3. OpenGL 3.0.** - -## Compiling -MaSzyna should work and compile natively under **Linux** and **Windows**. Other platforms are not tested. Full list of requirements is [here](#minimum-requirements) for runtime, and [here](#2-dynamic-libraries) for building. - -**Note:** Currently our dev team is too small to fully support compiling process. We do whatever we can, to fix and improve it, but still there may be some issues. - -**If you have any problems, feel free to send [issue](https://github.com/eu07/maszyna/issues), or write to us on [our dev chat](https://milek7.pl:8065/eu07/channels/dev).** - -**Known issues:** - - GLFW may have some problems with linking. - - there may be problems with order of linking x11, and other libs. - -Commands will be written in [`Bash`](https://www.gnu.org/software/bash/). No-Linux users must do in corresponding technology. - -0. Clone source code. - You may download source code [as ZIP archive](https://github.com/eu07/maszyna/archive/master.zip), or clone it by [`Git`](https://git-scm.com/). We won't provide tutorial to second one, the only note worth mention is that, repository contain submodules, so `--recursive` is needed. From now, it is assumed that your working directory is inside directory with unpacked source code. -1. Make directory, where build files will be stored, then enter inside it. - - $ mkdir build - $ cd ./build - -2. Generate makefile by CMake. Call: +- [Getting Started](#getting-started) + + - [Prerequisites](#prerequisites) - $ cmake ../ [flags] - - where flags may be: - - | Flag | Meaning | - |-----------------------------|-------------------| - | -DCMAKE_BUILD_TYPE=Debug | For debug build | - | -DCMAKE_BUILD_TYPE=Release | For release build | - | -DGLFW3_LIBRARIES='\' | To set path to GLFW. If other linker errors are present, it is possible to set other library paths as well, to do that corresponding variable must be fund in CMake files, then passed after `-D`. | - - Other CMake flags may be passed as well. - -3. After generation makefile, run make. + - [CMake flags](#cmake-flags) - make + - [Windows](#windows) + + - [Linux](#linux) + +- [Installing](#installing) + +- [Known Issues](#known-issues) + +- [Support](#support) + +- [License](#license) + -4. If everything went well, compilation process should be finished. -### Installing - As we don't have any install script, as `make install`, executable must be copied to install directory "by hand". +## Getting Started - Executable will be in `./bin` directory, named as: `eu07_yymmdd`, or `eu07_yymmdd_d`, where: - - `yy` is year, - - `mm` is month, - - `dd` is day - - `_d` is debug flag. +MaSzyna compiles and runs natively on **Linux** and **Windows**. Other platforms are not tested. - If you currently have MaSzyna assets, just copy executable to install directory. - You can download assets from [eu07.pl](https://eu07.pl/). +> **Heads-up** +> Our dev team is small; we keep improving the build process, but issues may still occur. If you get stuck, please ask on the [dev chat](https://milek7.pl:8065/eu07/channels/dev). - **Note:** Linux users may have issue, that `Rainsted` (third party starter), may not detect executable. In that case it is possible, to simulate Windows executable, by creation shell script, like this: - - **./eu07.exe** (which is technically shell script) +### Prerequisites - #!/bin/sh - ./eu07 $1 $2 $3 $4 $5 +> For runtime requirements see [Minimum Requirements](#minimum-requirements). - If it still won't work you may try to increase (by comments) file size up to 1MB. - -### Trailer -[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/BqmuKr4MYm8/0.jpg)](https://www.youtube.com/watch?v=BqmuKr4MYm8) -### [Screenshots](https://eu07.pl/galeria/) +**1) Software** _(oldest tested in parentheses)_ -![](https://eu07.pl/data/uploads/dodatki2017/e6act_4.png) -![](https://eu07.pl/data/uploads/gallery/2018/cien_2018.png) -[More...](https://eu07.pl/forum/index.php/topic,14630.0.html) -### Minimum Requirements -- OpenGL 1.5+ -- 15 GB free disk space -- sound card, support for OpenAL +- [CMake](https://cmake.org/) _(3.0)_ + +- [make](https://www.gnu.org/software/make/) + +- A C++ compiler with C++14 support (we use some C++17 features, but older compilers may still work): + + - **Windows:** Visual Studio 2022 + + - **Linux:** GCC _(12.3.1)_ + -### [License](LICENSE) +> **Note:** MinGW is currently **not supported**. + +**2) Libraries** _(oldest tested in parentheses)_ + +- [GLFW 3.x](https://www.glfw.org/) _(3.2.1)_ + If a link error occurs, pass `-DGLFW3_LIBRARIES=""` to CMake. + +- [GLM](https://glm.g-truc.net/) _(0.9.9.0)_ + +- [libserialport](https://sigrok.org/wiki/Libserialport) _(0.1.1)_ + +- [libsndfile](https://github.com/erikd/libsndfile) _(1.0.28)_ + +- [LuaJIT](http://luajit.org/) _(2.0.5)_ + +- [GLEW](http://glew.sourceforge.net/) _(2.1.0)_ + +- [libpng](http://www.libpng.org/pub/png/libpng.html) _(1.6.34)_ + +- [OpenAL](https://www.openal.org/) _(1.18.2)_ + +- **pthread** + +- [Python 2.7](https://www.python.org/) + +- [Asio](https://think-async.com/Asio) _(1.12)_ + + +**3) Graphics API** + +- **OpenGL 3.0** or newer +- **DirectX 12** via NVRHI (optional, Windows only, for Better Renderer) + + +### CMake flags + +| Flag | Meaning | +|------|---------| +| `-DCMAKE_BUILD_TYPE=Debug` | Debug build | +| `-DCMAKE_BUILD_TYPE=Release` | Release build | +| `-DCMAKE_BUILD_TYPE=RelWithDebInfo` | Release build with debug symbols | +| `-DWITH_BETTER_RENDERER=ON/OFF` | Enable/disable NVRHI-based renderer | + +> **Linux note:** `WITH_BETTER_RENDERER` uses DirectX 12 through NVRHI and is **not supported on Linux**. + + + + +## Windows + +```powershell +# Clone repository with submodules +git clone --recursive https://github.com/eu07/maszyna.git + +cd maszyna + +# Init vcpkg +call setup.bat + +# Create directory for CMake build files +mkdir build +cd build + +# Generate CMake project (replace %CONFIG% with Debug/Release/RelWithDebInfo) +cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=%CONFIG% + +# Build (replace %CONFIG% accordingly) +cmake --build . --config %CONFIG% --parallel + +``` + + + +## Linux + +```bash +# Install dependencies (Fedora/RHEL family) +sudo dnf install -y \ + @development-tools \ + cmake \ + mesa-libGL-devel \ + glew-devel \ + glfw-devel \ + python2-devel \ + libpng-devel \ + openal-soft-devel \ + luajit-devel \ + libserialport-devel \ + libsndfile-devel \ + gcc \ + g++ \ + wayland-devel \ + wayland-protocols-devel \ + libxkbcommon-devel + +# Clone repository with submodules +git clone --recursive https://github.com/eu07/maszyna.git + +cd maszyna + +# Create directory for CMake build files +mkdir build +cd build + +# Generate Makefiles (NVRHI is not supported on Linux) +cmake .. -DWITH_BETTER_RENDERER=OFF + +# Compile using all cores +make -j"$(nproc)" + +``` + +> **Tip (Ubuntu/Debian)**: Package names differ; install equivalent `build-essential`, `libgl1-mesa-dev`, `libglew-dev`, `libglfw3-dev`, `python2-dev`, `libpng-dev`, `libopenal-dev`, `libluajit-5.1-dev`, `libserialport-dev`, `libsndfile1-dev`, and Wayland/X11 dev packages as needed. + + +## Installing + +There is no `make install` yet. Copy the built executable to your MaSzyna installation manually. + +- Output directory: `./bin` + +- File name format: `eu07_YYYY-MM-DD_[_d]` + + - `YYYY-MM-DD` – build date + + - `` – short commit hash + + - `_d` – present in Debug builds + + +If you already have the MaSzyna assets, copy the executable to the install dir. Assets can be downloaded from [eu07.pl](https://eu07.pl/). + +**Rainsted on Linux** + +If `Rainsted` (a third‑party starter) fails to detect the executable under Linux, you can create a small wrapper script named `eu07.exe`: + +```sh +#!/bin/sh +./eu07 "$1" "$2" "$3" "$4" "$5" + +``` + +If detection still fails, padding the file (with comments) up to ~1 MB may help. + + +## Known Issues + +- **GLFW linking** – On some systems you must provide the GLFW library path explicitly with `-DGLFW3_LIBRARIES`. + +- **X11/Wayland linking order** – Linking order of X11 and related libs can matter. + +- **NVRHI on Linux** – The NVRHI/"Better Renderer" path targets DirectX 12 and is currently unsupported on Linux. + + + +## Support + +- **Issues:** [https://github.com/eu07/maszyna/issues](https://github.com/eu07/maszyna/issues) + +- **Developer chat:** [https://milek7.pl:8065/eu07/channels/dev](https://milek7.pl:8065/eu07/channels/dev) + +- **Project page:** [https://eu07.pl/](https://eu07.pl/) + +## Minimum requirements + +- Processor: **Intel Core i5-7600 or AMD Ryzen 5 1600** +- RAM: **16 GB** +- Graphics Card: **NVIDIA GeForce GTX 970 or AMD Radeon RX 580** +- **75 GB of free disk space** +- Sound card supporting OpenAL with stereo +- Optional COM ports for custom control panel setups. + +## License + +- Source code: [MPL 2.0](https://www.mozilla.org/en-US/MPL/2.0/) + +- Assets: [Custom license](https://eu07.pl/theme/Maszyna/dokumentacja/inne/readme_pliki/en-licence.html)