Schema and validator for a Lua gamemode's gamemode.json inside this roleplay framework. Holds id, title, version, apiVersion, entry script paths, dependencies, packages, collections and map lists, and Validate checks all of them (semver, id vs folder name, sh_/sv_/cl_ prefixes, package idents, map names). LuaPaths holds the relative path rules and realm detection used by the Lua loader.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using RoleplayFramework.Core;
namespace RoleplayFramework.Scripting;
/// <summary>Entry points of a gamemode, relative to the gamemode folder.</summary>
public sealed class GamemodeEntry
{
[System.Text.Json.Serialization.JsonPropertyName( "shared" )]
public string Shared { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "server" )]
public string Server { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "client" )]
public string Client { get; set; }
}
/// <summary>Maps a gamemode is meant for. "default" is used when the host doesn't choose one.</summary>
public sealed class GamemodeMaps
{
[System.Text.Json.Serialization.JsonPropertyName( "default" )]
public string Default { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "available" )]
public List<string> Available { get; set; } = new();
}
/// <summary>
/// <c>lua/gamemodes/<id>/gamemode.json</c>. Parsed with <see cref="Json"/>, then checked by <see cref="Validate"/>;
/// a manifest that fails validation is never loaded.
/// </summary>
public sealed class GamemodeManifest
{
[System.Text.Json.Serialization.JsonPropertyName( "id" )]
public string Id { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "title" )]
public string Title { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "version" )]
public string Version { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "apiVersion" )]
public int ApiVersion { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "author" )]
public string Author { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "description" )]
public string Description { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "entry" )]
public GamemodeEntry Entry { get; set; }
[System.Text.Json.Serialization.JsonPropertyName( "dependencies" )]
public List<string> Dependencies { get; set; } = new();
[System.Text.Json.Serialization.JsonPropertyName( "maps" )]
public GamemodeMaps Maps { get; set; }
/// <summary>sbox.game packages (models, materials, sounds, ...) this gamemode needs; mounted on server and clients.</summary>
[System.Text.Json.Serialization.JsonPropertyName( "packages" )]
public List<string> Packages { get; set; } = new();
/// <summary>Package collections: URLs or JSON files relative to the gamemode folder (e.g. "content.json").</summary>
[System.Text.Json.Serialization.JsonPropertyName( "collections" )]
public List<string> Collections { get; set; } = new();
/// <summary>The gamemode's default map, falling back to the built-in test world.</summary>
[System.Text.Json.Serialization.JsonIgnore]
public string DefaultMap => string.IsNullOrEmpty( Maps?.Default ) ? "minimal" : Maps.Default;
/// <summary>Maps to offer in the host form: the declared ones, always including the default.</summary>
[System.Text.Json.Serialization.JsonIgnore]
public List<string> AvailableMaps
{
get
{
var list = new List<string>( Maps?.Available ?? new List<string>() );
if ( !list.Contains( DefaultMap ) ) list.Insert( 0, DefaultMap );
return list;
}
}
/// <summary>Folder the manifest was found in, e.g. "lua/gamemodes/darkrp". Set by discovery, not read from JSON.</summary>
[System.Text.Json.Serialization.JsonIgnore]
public string Root { get; set; }
static readonly Regex VersionPattern = new( @"^\d+\.\d+\.\d+([-+][0-9A-Za-z.\-]+)?$" );
/// <summary>Returns every problem with this manifest (empty = valid). Does not check dependencies across gamemodes.</summary>
public List<string> Validate( string folderName )
{
var e = new List<string>();
if ( string.IsNullOrEmpty( Id ) ) e.Add( "missing 'id'" );
else if ( !FrameworkConfig.IsValidId( Id ) ) e.Add( $"'id' \"{Id}\" must be 1-32 characters of a-z, 0-9 or _" );
else if ( Id != folderName ) e.Add( $"'id' \"{Id}\" must match its folder name \"{folderName}\"" );
if ( string.IsNullOrWhiteSpace( Title ) ) e.Add( "missing 'title'" );
else if ( Title.Length > 64 ) e.Add( "'title' is longer than 64 characters" );
if ( string.IsNullOrEmpty( Version ) ) e.Add( "missing 'version'" );
else if ( !VersionPattern.IsMatch( Version ) ) e.Add( $"'version' \"{Version}\" is not semver (e.g. 1.2.0)" );
if ( ApiVersion == 0 ) e.Add( "missing 'apiVersion'" );
else if ( ApiVersion != FrameworkInfo.LuaApiVersion )
e.Add( $"'apiVersion' {ApiVersion} is not supported (this framework provides Lua API v{FrameworkInfo.LuaApiVersion})" );
if ( Entry is null ) e.Add( "missing 'entry'" );
else
{
if ( Entry.Shared is null && Entry.Server is null && Entry.Client is null ) e.Add( "'entry' needs at least one of shared/server/client" );
CheckEntry( e, "shared", Entry.Shared, "sh_" );
CheckEntry( e, "server", Entry.Server, "sv_" );
CheckEntry( e, "client", Entry.Client, "cl_" );
}
Dependencies ??= new();
foreach ( var d in Dependencies )
{
if ( !FrameworkConfig.IsValidId( d ) ) e.Add( $"dependency \"{d}\" is not a valid gamemode id" );
else if ( d == Id ) e.Add( "a gamemode cannot depend on itself" );
}
if ( Dependencies.Distinct().Count() != Dependencies.Count ) e.Add( "duplicate entries in 'dependencies'" );
foreach ( var pkg in Packages ?? new List<string>() )
if ( !ContentPackages.IsValidIdent( ContentPackages.Normalize( pkg ) ) ) e.Add( $"packages: '{pkg}' is not an org.name package ident" );
foreach ( var c in Collections ?? new List<string>() )
if ( ContentPackages.CheckCollectionSource( c ) is { } bad ) e.Add( $"collections: {bad}" );
if ( Maps is not null )
{
if ( Maps.Default is not null && MapCatalog.Validate( Maps.Default ) is { } bad ) e.Add( $"maps.default: {bad}" );
foreach ( var m in Maps.Available ?? new List<string>() )
if ( MapCatalog.Validate( m ) is { } badm ) e.Add( $"maps.available: {badm}" );
}
return e;
}
static void CheckEntry( List<string> e, string realm, string path, string prefix )
{
if ( path is null ) return;
var err = LuaPaths.CheckRelative( path );
if ( err is not null ) { e.Add( $"entry.{realm} \"{path}\": {err}" ); return; }
var file = path.Substring( path.LastIndexOf( '/' ) + 1 );
if ( !file.StartsWith( prefix ) ) e.Add( $"entry.{realm} \"{path}\" must be a {prefix}*.lua file" );
}
}
/// <summary>Path rules for everything the Lua loader reads.</summary>
public static class LuaPaths
{
static readonly Regex Allowed = new( @"^[a-z0-9_]+(/[a-z0-9_]+)*\.lua$" );
/// <summary>Validates a gamemode-relative script path. Returns null if fine, else the reason.</summary>
public static string CheckRelative( string path )
{
if ( string.IsNullOrEmpty( path ) ) return "empty path";
if ( path.Length > 128 ) return "path longer than 128 characters";
if ( path.Contains( ".." ) ) return "'..' is not allowed";
if ( path.StartsWith( "/" ) || path.Contains( ':' ) || path.Contains( '\\' ) ) return "must be a relative path using '/'";
if ( !Allowed.IsMatch( path ) ) return "only lowercase a-z, 0-9, _ and '/' are allowed, ending in .lua";
return null;
}
/// <summary>Realm a file belongs to, from its sh_/sv_/cl_ prefix; null if it has none.</summary>
public static LuaRealmKind? RealmOf( string path )
{
var file = path.Substring( path.LastIndexOf( '/' ) + 1 );
if ( file.StartsWith( "sh_" ) ) return LuaRealmKind.Shared;
if ( file.StartsWith( "sv_" ) ) return LuaRealmKind.Server;
if ( file.StartsWith( "cl_" ) ) return LuaRealmKind.Client;
return null;
}
}