The addon.json manifest model for a roleplay framework's Lua addon system, plus a VersionConstraint helper. Holds id, title, version, apiVersion, entry files, dependencies, gamemodes and content packages, validates them against the folder name and framework Lua API version, and parses/satisfies semver range constraints like >=1.2.0 and ^1.0.0.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using RoleplayFramework.Core;
namespace RoleplayFramework.Scripting;
/// <summary>
/// <c>lua/addons/<id>/addon.json</c>: an addon is Lua that runs on top of whatever gamemode the server uses
/// (a chat command, a HUD widget, an admin tool, ...). Server owners drop the folder into their data folder and switch
/// it on or off per server in framework.json (<c>"DisabledAddons"</c>).
///
/// <code>
/// { "id": "roll", "title": "Dice Roll", "version": "1.0.0", "apiVersion": 1,
/// "dependencies": { "otheraddon": ">=1.2.0" }, // other addons, with an optional version constraint
/// "gamemodes": [ "base" ], // only with these gamemodes (or gamemodes deriving from them)
/// "entry": { "shared": "sh_init.lua" }, // optional; default: every sh_/sv_/cl_ file in the folder
/// "packages": [], "collections": [] }
/// </code>
/// </summary>
public sealed class AddonManifest
{
[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; }
/// <summary>Optional entry files (relative to the addon folder). Without it, every top-level sh_/sv_/cl_ file loads.</summary>
[System.Text.Json.Serialization.JsonPropertyName( "entry" )]
public GamemodeEntry Entry { get; set; }
/// <summary>Other addons this one needs: id → version constraint ("" or "*" = any version).</summary>
[System.Text.Json.Serialization.JsonPropertyName( "dependencies" )]
public Dictionary<string, string> Dependencies { get; set; } = new();
/// <summary>Gamemodes this addon works with; matches the active gamemode or any gamemode it derives from. Empty = all.</summary>
[System.Text.Json.Serialization.JsonPropertyName( "gamemodes" )]
public List<string> Gamemodes { get; set; } = new();
[System.Text.Json.Serialization.JsonPropertyName( "packages" )]
public List<string> Packages { get; set; } = new();
[System.Text.Json.Serialization.JsonPropertyName( "collections" )]
public List<string> Collections { get; set; } = new();
/// <summary>Folder the manifest was found in, e.g. "lua/addons/roll". Set by discovery.</summary>
[System.Text.Json.Serialization.JsonIgnore]
public string Root { get; set; }
static readonly Regex VersionPattern = new( @"^\d+\.\d+\.\d+([-+][0-9A-Za-z.\-]+)?$" );
public static bool IsValidVersion( string v ) => v is not null && VersionPattern.IsMatch( v );
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 ( !IsValidVersion( 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 not null )
{
if ( Entry.Shared is null && Entry.Server is null && Entry.Client is null ) e.Add( "'entry' needs at least one of shared/server/client (or leave it out to load every file)" );
CheckEntry( e, "shared", Entry.Shared, "sh_" );
CheckEntry( e, "server", Entry.Server, "sv_" );
CheckEntry( e, "client", Entry.Client, "cl_" );
}
Dependencies ??= new();
if ( Dependencies.Count > 32 ) e.Add( "more than 32 dependencies" );
foreach ( var (dep, constraint) in Dependencies )
{
if ( !FrameworkConfig.IsValidId( dep ) ) e.Add( $"dependency \"{dep}\" is not a valid addon id" );
else if ( dep == Id ) e.Add( "an addon cannot depend on itself" );
if ( VersionConstraint.Check( constraint ) is { } bad ) e.Add( $"dependency \"{dep}\": {bad}" );
}
Gamemodes ??= new();
foreach ( var g in Gamemodes )
if ( !FrameworkConfig.IsValidId( g ) ) e.Add( $"gamemodes: \"{g}\" is not a valid gamemode id" );
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}" );
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>
/// Version constraints for addon dependencies. Space-separated parts that must all hold:
/// <c>*</c> or empty (any), <c>1.2.0</c> or <c>=1.2.0</c> (exactly), <c>>=1.2.0</c>, <c>>1.2.0</c>, <c><=2.0.0</c>,
/// <c><2.0.0</c>, <c>^1.2.0</c> (1.2.0 up to, not including, 2.0.0), <c>~1.2.0</c> (1.2.0 up to 1.3.0).
/// </summary>
public static class VersionConstraint
{
static readonly Regex Part = new( @"^(>=|<=|>|<|=|\^|~)?(\d+\.\d+\.\d+([-+][0-9A-Za-z.\-]+)?)$" );
/// <summary>Null if the constraint is well-formed, else why not.</summary>
public static string Check( string constraint )
{
if ( constraint is null ) return null;
if ( constraint.Length > 64 ) return "version constraint longer than 64 characters";
foreach ( var p in Parts( constraint ) )
if ( p != "*" && !Part.IsMatch( p ) ) return $"\"{constraint}\" is not a version constraint (e.g. \">=1.2.0\", \"^1.0.0\", \"*\")";
return null;
}
static IEnumerable<string> Parts( string c ) => (c ?? "").Split( ' ', StringSplitOptions.RemoveEmptyEntries );
public static bool Satisfies( string version, string constraint )
{
foreach ( var p in Parts( constraint ) )
{
if ( p == "*" ) continue;
var m = Part.Match( p );
if ( !m.Success ) return false;
var op = m.Groups[1].Value;
var target = m.Groups[2].Value;
int cmp = LuaSource.CompareVersions( version, target );
var t = Nums( target );
bool ok = op switch
{
">=" => cmp >= 0,
">" => cmp > 0,
"<=" => cmp <= 0,
"<" => cmp < 0,
"^" => cmp >= 0 && LuaSource.CompareVersions( version, $"{t[0] + 1}.0.0" ) < 0,
"~" => cmp >= 0 && LuaSource.CompareVersions( version, $"{t[0]}.{t[1] + 1}.0" ) < 0,
_ => cmp == 0,
};
if ( !ok ) return false;
}
return true;
}
static int[] Nums( string v ) => v.Split( '-', '+' )[0].Split( '.' ).Select( x => int.TryParse( x, out var n ) ? n : 0 ).ToArray();
}