Framework/Scripting/LuaSource.cs

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.

File Access
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/&lt;id&gt;/</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&amp;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.";
	}
}