Manages where the framework's gamemode and addon Lua comes from. Copies built-in gamemodes/addons into the game's data folder on first start, builds an in-memory snapshot of exactly the files a world will run (data folder copies override built-ins, framework core always from the game), and backs up / restores a data copy from the built-in version.
using System;
using System.Collections.Generic;
using System.Linq;
using RoleplayFramework.Bootstrap;
using RoleplayFramework.Diagnostics;
namespace RoleplayFramework.Scripting;
/// <summary>
/// Where gamemode Lua comes from.
///
/// <b>Data folder</b> (default everywhere: dedicated servers, local hosts, and the editor): on first start every
/// built-in gamemode is <i>copied</i> to <c>data/…/roleplay/lua/gamemodes/<id>/</c> and loaded from there, so
/// server owners and anyone hosting locally can edit gamemodes or drop in new ones without touching the game. A
/// gamemode folder in the data folder replaces the built-in one of the same id; built-in gamemodes that were never
/// copied are still available. (s&box only lets games write to their data folder; on a dedicated server that folder
/// is inside the server installation.)
///
/// <b>Built-in</b> (<c>"LuaSource": "builtin"</c>): the game's own files, for framework developers editing
/// <c>Assets/lua</c> directly.
///
/// Framework core files (<c>lua/framework</c>) always come from the game, so the framework API stays consistent.
///
/// Each world start (and <c>rp_lua_reload</c>) takes a <see cref="Snapshot"/>: an in-memory copy of exactly the files
/// that will run. The server loads from it and serves clients from it, so a file edited mid-session can't make the
/// served scripts disagree with what the server runs.
/// </summary>
public static class LuaSource
{
public const string DataRoot = "roleplay/lua";
public const string DataGamemodes = DataRoot + "/gamemodes";
public const string BuiltInGamemodes = GamemodeRegistry.GamemodesRoot; // "lua/gamemodes"
public const string DataAddons = DataRoot + "/addons";
public const string BuiltInAddons = AddonRegistry.AddonsRoot; // "lua/addons"
public const string BackupRoot = "roleplay/lua_backups";
const int MaxFiles = 3000;
const int MaxFileChars = 512 * 1024;
/// <summary>Where each gamemode ("id") and addon ("addon:id") in the last snapshot came from: "data" or "built-in".</summary>
public static IReadOnlyDictionary<string, string> Origins => _origins;
static readonly Dictionary<string, string> _origins = new();
public static BaseFileSystem Current { get; private set; }
/// <summary>
/// True when gamemodes are loaded from the data folder (the default everywhere, editor included).
/// Only "builtin" (for framework developers editing Assets/lua directly) turns it off.
/// </summary>
public static bool UsesDataFolder => FrameworkHost.Config.LuaSource != "builtin";
public static string DataFolderPath => FileSystem.Data.GetFullPath( DataRoot );
static bool IsCopyable( string path ) =>
path.EndsWith( ".lua", StringComparison.OrdinalIgnoreCase ) || path.EndsWith( ".json", StringComparison.OrdinalIgnoreCase )
|| path.EndsWith( ".txt", StringComparison.OrdinalIgnoreCase ) || path.EndsWith( ".md", StringComparison.OrdinalIgnoreCase );
/// <summary>Copies built-in gamemodes that the data folder doesn't have yet. Never overwrites an existing copy.</summary>
public static void EnsureDataCopy()
{
if ( !UsesDataFolder ) return;
var src = FileSystem.Mounted;
var dst = FileSystem.Data;
if ( !src.DirectoryExists( BuiltInGamemodes ) ) return;
WriteReadme();
foreach ( var id in src.FindDirectory( BuiltInGamemodes, "*", false ) )
{
if ( dst.FileExists( $"{DataGamemodes}/{id}/gamemode.json" ) ) continue;
int n = CopyTree( src, $"{BuiltInGamemodes}/{id}", dst, $"{DataGamemodes}/{id}" );
RpLog.Info( "lua", $"Copied built-in gamemode '{id}' ({n} files) to {DataFolderPath}/gamemodes/{id} - edit it there" );
}
if ( src.DirectoryExists( BuiltInAddons ) )
{
foreach ( var id in src.FindDirectory( BuiltInAddons, "*", false ) )
{
if ( dst.FileExists( $"{DataAddons}/{id}/addon.json" ) ) continue;
if ( !src.FileExists( $"{BuiltInAddons}/{id}/addon.json" ) ) continue;
int n = CopyTree( src, $"{BuiltInAddons}/{id}", dst, $"{DataAddons}/{id}" );
RpLog.Info( "lua", $"Copied built-in addon '{id}' ({n} files) to {DataFolderPath}/addons/{id}" );
}
}
WarnAboutNewerBuiltIns();
}
static int CopyTree( BaseFileSystem src, string from, BaseFileSystem dst, string to )
{
int n = 0;
foreach ( var rel in src.FindFile( from, "*", true ) )
{
if ( !IsCopyable( rel ) ) continue;
var target = $"{to}/{rel}";
var dir = target.Substring( 0, target.LastIndexOf( '/' ) );
if ( !dst.DirectoryExists( dir ) ) dst.CreateDirectory( dir );
dst.WriteAllText( target, src.ReadAllText( $"{from}/{rel}" ) );
n++;
}
return n;
}
static void WriteReadme()
{
var path = $"{DataRoot}/README.txt";
if ( FileSystem.Data.FileExists( path ) ) return;
if ( !FileSystem.Data.DirectoryExists( DataRoot ) ) FileSystem.Data.CreateDirectory( DataRoot );
FileSystem.Data.WriteAllText( path, """
Roleplay Framework - your gamemodes
====================================
gamemodes/<id>/ holds the gamemodes this server runs. They were copied from the game on first start
and are yours to edit. A folder here replaces the built-in gamemode with the same id.
Add a gamemode: create gamemodes/<newid>/gamemode.json (+ Lua files), then set "DefaultGamemode"
in framework.json or pick it in Create Local Server.
Apply changes: run rp_lua_reload in the server console (or restart the server).
Start over: run rp_lua_restore <id> - your current copy is backed up to lua_backups/ first.
addons/<id>/ addons: Lua that runs on top of any gamemode (addon.json + sh_/sv_/cl_ files).
Every installed addon is on; list them with rp_addons , switch with
rp_addon_disable <id> / rp_addon_enable <id> (saved in framework.json), then rp_lua_reload.
Files must be lowercase with sh_ (shared), sv_ (server only) or cl_ (client) prefixes.
sv_ files never leave the server. sh_ and cl_ files are sent to players when they join.
API reference: Docs/LUA_API.md in the framework.
""" );
}
static void WarnAboutNewerBuiltIns()
{
var builtIn = GamemodeRegistry.Discover( FileSystem.Mounted, makeCurrent: false );
foreach ( var (id, gm) in builtIn.Valid )
{
var path = $"{DataGamemodes}/{id}/gamemode.json";
if ( !FileSystem.Data.FileExists( path ) ) continue;
if ( !Json.TryDeserialize( FileSystem.Data.ReadAllText( path ), out GamemodeManifest mine ) || mine is null ) continue;
if ( CompareVersions( mine.Version, gm.Version ) < 0 )
RpLog.Warn( "lua", $"The game ships a newer '{id}' ({gm.Version}) than your copy ({mine.Version}). Run 'rp_lua_restore {id}' to update (your copy is backed up first)." );
}
}
/// <summary>Compares "1.2.3" style versions numerically (pre-release suffixes are ignored).</summary>
public static int CompareVersions( string a, string b )
{
int[] Parse( string v ) => (v ?? "0").Split( '-', '+' )[0].Split( '.' ).Select( p => int.TryParse( p, out var n ) ? n : 0 ).Concat( new[] { 0, 0, 0 } ).Take( 3 ).ToArray();
var x = Parse( a );
var y = Parse( b );
for ( int i = 0; i < 3; i++ ) if ( x[i] != y[i] ) return x[i].CompareTo( y[i] );
return 0;
}
/// <summary>Builds the in-memory set of Lua files the next world will run, and makes it <see cref="Current"/>.</summary>
public static BaseFileSystem Snapshot()
{
var mem = BuildSnapshot( out var origins );
_origins.Clear();
foreach ( var (k, v) in origins ) _origins[k] = v;
Current = mem;
return mem;
}
/// <summary>Builds a snapshot without making it current (e.g. to list addons while no world runs).</summary>
public static BaseFileSystem BuildSnapshot( out Dictionary<string, string> origins )
{
var mem = FileSystem.CreateMemoryFileSystem();
var mounted = FileSystem.Mounted;
var _origins = origins = new Dictionary<string, string>();
int files = 0;
void Copy( BaseFileSystem src, string from, string to )
{
foreach ( var rel in src.FindFile( from, "*", true ) )
{
if ( !IsCopyable( rel ) ) continue;
if ( ++files > MaxFiles ) throw new InvalidOperationException( $"more than {MaxFiles} Lua files" );
var text = src.ReadAllText( $"{from}/{rel}" );
if ( text.Length > MaxFileChars ) { RpLog.Warn( "lua", $"Skipped {from}/{rel}: larger than {MaxFileChars} characters" ); continue; }
var target = $"{to}/{rel}";
mem.CreateDirectory( target.Substring( 0, target.LastIndexOf( '/' ) ) );
mem.WriteAllText( target, text );
}
}
if ( mounted.DirectoryExists( LuaRealm.FrameworkRoot ) ) Copy( mounted, LuaRealm.FrameworkRoot, LuaRealm.FrameworkRoot );
var dataIds = new HashSet<string>();
if ( UsesDataFolder && FileSystem.Data.DirectoryExists( DataGamemodes ) )
{
foreach ( var id in FileSystem.Data.FindDirectory( DataGamemodes, "*", false ) )
{
if ( !FileSystem.Data.FileExists( $"{DataGamemodes}/{id}/gamemode.json" ) ) continue;
Copy( FileSystem.Data, $"{DataGamemodes}/{id}", $"{BuiltInGamemodes}/{id}" );
dataIds.Add( id );
_origins[id] = "data";
}
}
if ( mounted.DirectoryExists( BuiltInGamemodes ) )
{
foreach ( var id in mounted.FindDirectory( BuiltInGamemodes, "*", false ) )
{
if ( dataIds.Contains( id ) ) continue;
Copy( mounted, $"{BuiltInGamemodes}/{id}", $"{BuiltInGamemodes}/{id}" );
_origins[id] = "built-in";
}
}
// Addons: same rule as gamemodes; a data-folder copy replaces the built-in addon of the same id.
var dataAddons = new HashSet<string>();
if ( UsesDataFolder && FileSystem.Data.DirectoryExists( DataAddons ) )
{
foreach ( var id in FileSystem.Data.FindDirectory( DataAddons, "*", false ) )
{
if ( !FileSystem.Data.FileExists( $"{DataAddons}/{id}/addon.json" ) ) continue;
Copy( FileSystem.Data, $"{DataAddons}/{id}", $"{BuiltInAddons}/{id}" );
dataAddons.Add( id );
_origins["addon:" + id] = "data";
}
}
if ( mounted.DirectoryExists( BuiltInAddons ) )
{
foreach ( var id in mounted.FindDirectory( BuiltInAddons, "*", false ) )
{
if ( dataAddons.Contains( id ) || !mounted.FileExists( $"{BuiltInAddons}/{id}/addon.json" ) ) continue;
Copy( mounted, $"{BuiltInAddons}/{id}", $"{BuiltInAddons}/{id}" );
_origins["addon:" + id] = "built-in";
}
}
return mem;
}
/// <summary>
/// Backs up the data copy of a gamemode (or, if there is no built-in gamemode with that id, an addon; force the
/// addon with "addon:id") and replaces it with the built-in version.
/// </summary>
public static string Restore( string id )
{
bool addon = id?.StartsWith( "addon:" ) == true;
if ( addon ) id = id.Substring( 6 );
if ( !Core.FrameworkConfig.IsValidId( id ) ) return "Usage: rp_lua_restore <gamemode id> | addon:<addon id>";
if ( !addon && !FileSystem.Mounted.FileExists( $"{BuiltInGamemodes}/{id}/gamemode.json" ) && FileSystem.Mounted.FileExists( $"{BuiltInAddons}/{id}/addon.json" ) )
addon = true;
var builtIn = addon ? $"{BuiltInAddons}/{id}" : $"{BuiltInGamemodes}/{id}";
if ( !FileSystem.Mounted.FileExists( $"{builtIn}/{(addon ? "addon" : "gamemode")}.json" ) ) return $"There is no built-in {(addon ? "addon" : "gamemode")} '{id}' to restore.";
var data = FileSystem.Data;
var mine = addon ? $"{DataAddons}/{id}" : $"{DataGamemodes}/{id}";
string backup = null;
if ( data.DirectoryExists( mine ) )
{
backup = $"{BackupRoot}/{(addon ? "addon-" : "")}{id}-{DateTime.UtcNow:yyyyMMdd-HHmmss}";
CopyTree( data, mine, data, backup );
data.DeleteDirectory( mine, true );
}
int n = CopyTree( FileSystem.Mounted, builtIn, data, mine );
return $"Restored '{id}' from the game ({n} files){(backup is null ? "" : $"; your previous copy is in {FileSystem.Data.GetFullPath( backup )}")}. Run rp_lua_reload to apply.";
}
}