BeamNG.Earth README

项目的 README,来自 github.com/TecnaGamer/BeamNG.Earth。合并为一个 markdown 文件:README.md。

BeamNG.Earth

A 1:1 scale, streamed Earth for BeamNG.drive: drive anywhere on the planet on real elevation data and satellite imagery, with distance-based level of detail and the real curvature of the Earth.

Status: beta (see VERSION). Tested on BeamNG.drive 0.40.4 on Linux (Vulkan) and 0.40.3 on the Steam Deck. See docs/ROADMAP.md for what is coming.

Community: join the TGForever Discord, discord.gg/tgf, and head to the #beamng-earth channel to chat about the mod, get help, report bugs, help with its development, and get an IP to join a BeamMP.Earth server (see Multiplayer).

Help with multiplayer comes from the TGForever Discord too. BeamNG.Earth isn't like a normal BeamNG mod (it runs its own app next to the game), so if something isn't working with BeamMP, it's almost certainly a BeamNG.Earth problem, not a BeamMP one. Please don't contact the BeamMP team or open BeamMP support tickets about it.

You can help support development by reporting issues, contributing code and sending pull requests, or donating. Thank You!

Features (working today)

The world

Time, weather and physics

Driving and traffic

Multiplayer (BeamMP, in testing)

Map and navigation

Interface and tools

How it works

Install and play

You need: BeamNG.drive (tested with 0.40.x) on Steam, free disk space for the map download cache (it grows as you visit places, up to 20 GB by default; Settings > Storage > "Cache size limit" takes any size in GB, 0 for no limit), and an internet connection (the map is downloaded while you play).

  1. Download the file for your system from the Releases page:
    • Windows: BeamNG.Earth-<version>.exe. Windows may warn about an unknown app: More info > Run anyway.
    • Linux: BeamNG.Earth-<version>-x86_64.AppImage. Make it executable (right-click > Properties > "Allow executing", or chmod +x).
  2. Run it (with Steam running). A console window opens (like BeamMP's launcher); it copies the mod into the game, starts the world server and starts BeamNG.drive. Closing the game stops the server.
    • Linux, native game: started with the engine patches (tools/gcpatch: grass kept across block moves, with two more opt-in patches for testing) already applied, no Steam launch options needed.
    • Linux, Windows build under Proton: the AppImage sees the Proton setting and starts that build through Steam (the server runs natively). The .exe also works inside the game's Proton prefix (for example with protontricks' launcher).
    • Linux, Steam as a Flatpak (or snap): the mod goes into the game's folder inside the Flatpak (~/.var/app/com.valvesoftware.Steam/...) and the game starts through Steam (without the grass patch).
    • The Windows build shows BeamNG's launch options dialog (renderer, safe mode) as usual; --gfx dx11 / --gfx vk / --gfx dx12 skip it with that renderer.
  3. Play: in the game, go to Freeroam and pick the BeamNG.Earth level. A welcome page explains the basics the first time. Press M for the world map: search a place or an address, right-click to teleport, left-click to set a GPS route, and Autodrive to let the car drive it.

From the source instead (any system with Python 3.10+): download this project (the green Code button > Download ZIP) and unzip it. Install once (and after each update): double-click run_server.bat (Windows) or run python3 install.py (Linux). Then start the server with run_server.bat / ./run_server.sh, keep its window open, and start the game yourself. Or run python3 launcher.py, which also starts the game like the downloads do.

Updating: the mod tells you in game when a newer version is on GitHub. Download the new file and run it (from the source: unzip it over the old folder and run the installer again).

Development builds (pre-releases): every change pushed to the dev branch is built automatically and published as a GitHub pre-release named after the beta it follows, with a build number (for example 1.7.2-beta.dev.37). They have the newest fixes and features, but they are built from the development branch and not thoroughly tested: expect bugs, and things may change or break from one build to the next. The beta releases are the tested ones. A development build says so in game, and its update check offers the next development build (or the next beta, if that is newer); a beta only ever offers betas. Only the newest three development builds are kept on the releases page.

Uninstalling: delete the beamng_earth folder in <BeamNG user folder>/current/mods/unpacked/ and the downloaded file (or this folder); the map cache is .cache/beamng-earth in your home folder (~/.cache/beamng-earth on Linux, C:\Users\<you>\.cache\beamng-earth on Windows).

The map cache on another drive: in the game, settings page > Download cache > Cache folder: Change... opens your system's folder window, or type or paste a folder and press Use. Or start the app once with --cache-dir PATH (e.g. a shortcut to BeamNG.Earth-<version>.exe --cache-dir "D:\BeamNG.Earth cache"). It is used from the next start and remembered; default goes back. Move the old cache folder there first to keep what is already downloaded.

BeamNG.drive installed somewhere else (not in a Steam library the app finds, e.g. another launcher): the app asks where it is the first time (Enter opens your system's folder window, or type or paste the folder) and remembers it; --game-dir PATH sets it too, --game-dir default forgets it. A game folder outside Steam is started directly. On Linux, BeamMP's launcher finds the game only in Steam's libraries, so BeamMP isn't started with such a copy.

More detail (traffic, the status bar, reporting problems, troubleshooting): docs/QUICKSTART.md.

Compute sharing (optional, for tinkerers): another computer on your network can build part of the distant landscape for you. On it, from a copy of the same version's source: python3 server/peerwork.py serve (port 47620, --workers N processes; it downloads its own map data). On the computer you play on, set BNGE_PEERS to the helpers before starting BeamNG.Earth, for example BNGE_PEERS=192.168.1.20:47620,192.168.1.21:47620. Helpers running other code are left out, and anything a helper fails on is built on your own computer. Only use helpers on a network you trust: the connection is not encrypted.

Developer setup

python3 install.py also works from a checkout (mod copy, .venv, then python3 start.py); by hand:

  1. Python 3.10+ with the packages in server/requirements.txt. The server needs its Rust module: the checkout carries it built for Linux x86-64 (server/earthfast.abi3.so) and Windows (server/earthfast.pyd); after changing native/earthfast, or on another system, build it with python3 tools/build_native.py (Rust's cargo; --windows cross-builds the .pyd with cargo-zigbuild).
  2. Copy (or sync) mod/beamng_earth/ to <BeamNG user folder>/current/mods/unpacked/beamng_earth/.
  3. Start the server: python3 server/earthd.py
  4. Start BeamNG.drive and load the BeamNG.Earth level. The mod connects to the server and streams the world; the status bar at the top shows where you are and the loading, M opens the world map (search, teleport, GPS routes, Autodrive).

Player downloads: python3 tools/build_app.py builds this system's AppImage / .exe (PyInstaller; see its docstring; for the .exe run tools/build_bootloader.py first: a bootloader built from source, fewer antivirus false positives); GitHub Actions (.github/workflows/release.yml) builds both and publishes the release v<VERSION> whenever main gets a VERSION without one. Release zip of the source: python3 tools/package.py.

Tests: cd server && python3 -m unittest discover -s tests -t tests and cd mod/tests && for f in test_*.lua; do luajit $f; done (no luajit: pip install lupa, then python3 tools/run_lua_tests.py).

Multiplayer (BeamMP)

BeamNG.Earth runs on BeamMP servers (in testing): drive the real world together.

Support for BeamNG.Earth on BeamMP comes from us, not from BeamMP. For questions or help with joining or hosting a BeamNG.Earth server, join the TGForever Discord: discord.gg/tgf. BeamNG.Earth isn't like a normal BeamNG mod: it needs its own app running next to the game. If something isn't working, it's almost certainly a BeamNG.Earth problem, not a BeamMP one, so please don't contact the BeamMP team or open BeamMP support tickets when you run into trouble getting BeamNG.Earth to work with BeamMP.

BeamNG.Earth servers are hidden from players who don't run BeamNG.Earth. BeamMP can't install BeamNG.Earth for a player who joins, because it needs its own app (a launcher and a world server that builds the world on each player's computer). So BeamMP's own server list never shows these servers. Players with the BeamNG.Earth app find them in the BeamNG.Earth category of BeamMP's server browser, or join by Direct Connect.

Joining a server

  1. Start the BeamNG.Earth app (the same version as the server's). It starts BeamMP with the game: the official BeamMP launcher, unchanged (BeamMP's code is AGPL-3.0, github.com/BeamMP). If BeamMP isn't installed, the app asks once: Yes / No / Don't ask again / Have it already (the last one asks where your launcher is: Enter opens your system's file window, or type or paste the path; --beammp-launcher PATH sets it too, and it is kept for the next starts). To change it later: settings page > Multiplayer > BeamMP launcher.
    • Windows: Yes downloads BeamMP's official launcher from BeamMP's GitHub releases (checked against the checksum BeamMP publishes; Windows Firewall then asks once whether it may use the network: allow it).
    • Linux and Steam Deck: BeamMP publishes no Linux download, so Yes builds its launcher on your computer from BeamMP's source, the newest version that passed BeamMP's own tests, in an Ubuntu container (podman or docker: SteamOS has podman; about a minute on a Steam Deck). A launcher you built yourself is used when found (a BeamMP-Launcher folder in your home folder or one folder down, e.g. ~/Games/BeamMP-Launcher, or ~/.local/share; or answer "Have it already", or set BEAMMP_LAUNCHER).
    • The setting Start BeamMP with BeamNG.Earth (Pause menu > BeamNG.Earth > Multiplayer) turns this off or back on; --no-beammp starts the game without BeamMP once. If BeamMP is not ready within 30 seconds the app stops it and carries on in single player (--beammp-wait SECONDS waits longer, up to 600).
  2. In the game: main menu > More > BeamMP, log in (an account or a guest).
  3. Pick the BeamNG.Earth category in BeamMP's server browser: the servers running BeamNG.Earth (search, filters, favorites and details as for the other servers), the official server at the top. They are listed only there, for players who have BeamNG.Earth. A private server: Direct Connect with its address (the TGForever Discord server has some). Every player needs the BeamNG.Earth app running: each builds the world on their own computer. (Starting the BeamMP launcher yourself first still works: the app then starts just the world server.)

Leaving a server turns BeamNG.Earth back on (joining one switches your other mods off).

You are sent to where the others are. Cars show in the right place in everyone's world; other players show on the world map (M) as green arrows; players far away (another country) are hidden until you meet. Crash damage: a crash you watch keeps the damage your own game worked out; a car that crashed out of your sight takes on its owner's damage (broken parts and dents) once it comes within about 0.6 miles.

Each player's app builds the world around them on their own computer. Sharing the work (in testing): the BeamMP server keeps what its players build of the slowest part of the world, the road levelling plans of each map area (compressed, a few hundred KB each), and sends it to every player who comes there later, this session or the next. A player near the others gets much of it from the server instead of building it, which is quickest on slower computers. It all goes through the BeamMP connection itself, nothing to set up or forward, and only between players running the same BeamNG.Earth version with the same settings. A server can also hold baked packs of whole areas (put .bnge files in Resources/Server/BeamNGEarth/bake/), and the machine running the server can build ahead of the players itself (the share helper, below).

Hosting a server: download BeamNG.Earth-BeamMP-Server-<version>.zip from the Releases page and follow the guide inside (BeamNG.Earth-README.md). In short: unzip it into a BeamMP server's folder, set Map = "/levels/beamng_earth/info.json" in ServerConfig.toml, forward the server's port (TCP and UDP) for players over the internet, and start it (its log shows [BeamNG.Earth] plugin loaded). Which list it is on: Private = false with your AuthKey puts it on the BeamNG.Earth list (the in-game category) and the plugin keeps it off BeamMP's own public list, so players without BeamNG.Earth never see it; Private = true, or no AuthKey: on no list, players use Direct Connect. The plugin lists the server once a minute with curl (Linux, and Windows 10 and later). Update the server zip with every release: it carries the mod the server sends to players. The server's time and weather for everyone (G.TIME: real or a fixed / running time such as '20:30'; G.WEATHER: real or clear, cloudy, rain, storm, snow, fog) are set near the top of Resources/Server/BeamNGEarth/main.lua. The server needs no world data and little CPU. From the source, python3 tools/package.py --beammp builds the same zip. Releases may also carry ready-made host bundles (BeamNG.Earth-Host-<version>-Windows.zip / -Linux-x86_64.zip, built by tools/build_host.py): the zip above plus BeamMP's own unmodified server program (v3.9.3, checked against the checksum BeamMP publishes), its licence and source, and a ServerConfig.toml with an empty AuthKey for your own.

Shared road plans (experimental, off by default): BeamNG.Earth --world-cache export|serve|fetch|verify packs the road plans one machine has built into a checked bundle that other players can fetch and reuse, so their companions skip planning those roads; see docs/SHARED_WORLD.md.

The server keeps its players' shared world building in Resources/Server/BeamNGEarth/store (up to G.SHARE_STORE_MB, 2 GB by default; the pieces used longest ago go first) and sends at most G.SHARE_OUT_KBPS (1 MB/s) of it, both near the top of main.lua. Share helper (in testing): to let the server's machine build ahead of its players, run BeamNG.Earth's world server next to it, from the source: python3 server/sharehelper.py --share-dir <BeamMP server>/Resources/Server/BeamNGEarth --cache <a folder for its map data> --procs 4. It needs the same BeamNG.Earth version as the players and a few GB of disk for each area.

Usage statistics (telemetry)

To see how many people play and how hard we are pushing the free map-data services we rely on, the world server sends a small anonymous report every 5 minutes: a random install id (created on your machine; no name, account or hardware id), the app version and operating system, whether the game is connected, whether it is a BeamMP session, and how many requests went to each data source (with their errors and rate limits). With Performance data ticked it also sends the game's frame rate and hitches, how well the world keeps up, your CPU / GPU model and settings, and error codes. No positions or places are sent. The collector looks up your country from the connection's address and does not keep the address.

The public numbers (players online, peaks, history, countries with at least 5 players) are at https://earth.tgforever.net/players, and the performance numbers (groups of at least 5 players) at https://earth.tgforever.net/performance.

Nothing is sent until you choose. The welcome screen asks first, with a main switch and two parts (performance data, network load); how the boxes start depends on your computer's time zone (nothing ticked in the EU and some other places). Change it any time in BeamNG.Earth's settings page, Interface (from the next report on), or set the environment variable BNE_TELEMETRY=off before starting BeamNG.Earth. Reports are never sent in offline mode (--offline). Every field, why we want it and what happens to it: TELEMETRY.md.

Data sources and attribution

The repository contains only code; all map data is downloaded at runtime and cached locally.

License

Code: MIT, see LICENSE. BeamNG.drive is a trademark of BeamNG GmbH; this is an unofficial fan project and contains no BeamNG assets.

BeamNG.Earth (TecnaGamer/BeamNG.Earth)

正在搜索数据库…

这是什么?BeamNG.Earth 是 BeamNG.drive 的一个模组,它会把 1:1 比例的真实地球模型流式加载到游戏中,使用真实的海拔数据和卫星/航拍影像,根据距离调整细节等级,并还原真实的地球曲率。
这是游戏模组还是独立应用?它是一个 BeamNG.drive 模组,搭配一个小型本地 Python 辅助服务器。模组在游戏内加载地形,服务器则下载海拔和影像数据,并通过本地 socket 传输过去,因为游戏的 Lua 本身无法直接访问互联网。
我该如何安装并开始玩?从 Releases 页面下载适用于你操作系统的启动器(Windows 为 .exe,Linux 为 .AppImage),在 Steam 运行的情况下执行它。它会把模组复制到游戏中、启动世界服务器并打开 BeamNG.drive;然后在自由漫游(Freeroam)中选择 BeamNG.Earth 关卡即可。你也可以从源代码运行:执行 'python3 install.py',然后运行 'runserver.bat' 或 './runserver.sh'。
使用它需要安装 BeamNG.drive 和 Python 吗?你需要在 Steam 上已安装 BeamNG.drive(已在 0.39.x 版本上测试),并为地图缓存留出足够的磁盘空间;如果不使用预构建的启动器,而是从源代码运行,还需要 Python 3.10+,并安装 server/requirements.txt 中列出的软件包。
这个项目是否已经完成且稳定,还是仍不成熟?它被标注为 beta 版,目前仅在 Linux/Vulkan 环境下、BeamNG.drive 0.39.4 上测试过;高速流式加载、真实视距、道路、水域、导航、交通和城市等功能,在路线图中仍被列为即将推出。
没有网络连接也能玩吗?第一次进入某个区域时需要联网,因为地形是实时流式加载的;但一旦地图瓦片被缓存,你就可以离线重玩这些区域,这些瓦片来自下载缓存,其上限可配置,范围为 5-50 GB。
既然它使用真实地图数据,许可证方面是怎么回事?模组自身的代码采用 MIT 许可证,但部分下载的影像(例如 2023 年的 Sentinel-2 无云版本)仅以非商业用途的 CC BY-NC-SA 许可证提供;本项目是非官方的粉丝项目,不包含任何 BeamNG 资源。
交通 AI 真的能在这些现实世界的道路上运行吗?能。模组会根据你周围的真实道路构建 BeamNG 的道路网络,包括车道、限速和交通信号灯,因此游戏原版的 AI、交通和警察系统都能在其中运行。
游戏内的天气与现实情况一致吗?一致。它会根据你当前所在位置从 Open-Meteo 获取实时天气(云量、风力、雨雪、温度),并依据真实时区和时钟设置太阳和月亮的位置,再将这些数据输入 BeamNG 自身的天气系统。
地图数据来自哪里?海拔数据来自各国的激光雷达(lidar)数据集以及 Copernicus 30 米数据;影像来自开放的州级/国家级正射影像以及 Sentinel-2 无云影像;道路和建筑数据来自 Overture Maps 和 OpenStreetMap。完整致谢信息见 CREDITS.md。
大小
1.3 GB
星标
2.3K
时长
1个月
提交 · 90 天