From 00249b265a18cfc059006de21d43c555d96e01b7 Mon Sep 17 00:00:00 2001 From: Exil Productions Date: Mon, 8 Sep 2025 22:26:40 +0200 Subject: [PATCH] Update Readme --- README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d215208..713751a 100644 --- a/README.md +++ b/README.md @@ -1 +1,97 @@ -# AddonLib \ No newline at end of file +# AddonLib + +AddonLib + +Overview +- AddonLib is a .NET 8 library for building addon-enabled applications in C#. +- It lets app developers expose a host API to addons and raise callbacks; addon developers implement addons that react to callbacks and call back into the host. + +Projects +- AddonLib: core library containing attributes, base classes, and AddonManager. +- HostApp: example host application that integrates AddonLib and auto-loads plugins from a Plugins folder. +- SampleAddon: example addon implementing AddonBase and reacting to host callbacks. + +Key concepts +- Assembly-level addon metadata: [assembly: Addon(name, author, version)] +- Addon base class: inherit from AddonBase to access Context, Services, and host helper methods. +- Callbacks: mark methods with [AddonCallback("EventName")] (or omit the name to use the method name). The host raises these events so addons receive notifications. +- Host API exposure: + - Methods: mark host methods with [AddonCallable("Name?")] so addons can call them via CallHost. + - Fields/Properties: mark with [AddonAccessible(ReadOnly|ReadWrite, "Name?")] so addons can GetHostValue/SetHostValue. + +Auto plugin loading +- AddonManager can auto-create a Plugins directory and auto-load all addon DLLs from it at startup. +- Default directory is AppContext.BaseDirectory/Plugins (configurable via constructor). + +Host quick start +1) Create and configure the manager in your app entry point: + - `var manager = new AddonManager("Plugins", autoInitialize: true);` +2) Register an API object with attributes for addons to call and access: + - `manager.RegisterHostApi(new HostApi(manager));` +3) Raise callbacks from host code so addons can react: + - Mark a host method with [AddonCallback] and inside it call `manager.RaiseAddonCallback()` (uses the caller method name as event), or + - Call `manager.RaiseCallback(MethodBase.GetCurrentMethod(), args...)` to use an explicit [AddonCallback("EventName")] annotation. + +Addon quick start +1) Mark the assembly with metadata: + - `[assembly: Addon("My Addon", "Me", "1.0.0")]` +2) Create a class inheriting AddonBase: + - `public sealed class MyAddon : AddonBase { ... }` +3) Add callback methods annotated with [AddonCallback]: + - `[AddonCallback] void OnTick(AddonContext ctx) { var message = CallHost("Echo", "Hi"); }` +4) Optional: use GetHostValue/SetHostValue for members marked [AddonAccessible]. +5) Build the addon and drop the resulting DLL into the host Plugins folder. + +Examples in this repository +- HostApp demonstrates: + - Initializing AddonManager with auto-initialization and autoload. + - Registering a HostApi with [AddonCallable], [AddonAccessible], and [AddonCallback]. + - Raising callbacks using `manager.RaiseAddonCallback()`. +- SampleAddon demonstrates: + - Declaring addon metadata. + - Subscribing to the host OnTick event with [AddonCallback] and using CallHost/GetHostValue/SetHostValue. + +Attributes reference (summary) +- AddonAttribute (assembly): Addon(name, author, version) +- AddonCallbackAttribute (method): optional EventName; if omitted, method name is used. AllowMultiple = true to bind one method to multiple events. +- AddonCallableAttribute (method): optional Name; if omitted, method name is used. Host methods callable by addons. +- AddonAccessibleAttribute (field/property): access mode ReadOnly or ReadWrite and optional Name; if omitted, member name is used. + +AddonBase essentials +- Context: Addon metadata and assembly. +- Services: optional IServiceProvider provided by the host. +- CallHost(name, params object?[] args) +- GetHostValue(name) +- SetHostValue(name, value) +- Lifecycle: OnLoaded(), OnUnloading() + +AddonManager essentials +- Constructors: + - AddonManager() – no auto init + - AddonManager(string? pluginsDirectory, bool autoInitialize = true, IServiceProvider? services = null) +- Properties: PluginsDirectory, LoadedAddons +- API exposure: RegisterHostApi(object host) +- Loading: + - InitializePluginsDirectory(createIfMissing = true) + - LoadAllFromPluginsDirectory(SearchOption.TopDirectoryOnly) + - LoadFrom(string assemblyPath) + - LoadFrom(Assembly assembly) +- Callbacks: + - RaiseCallback(string eventName, params object?[] args) + - RaiseCallback(MethodBase method, params object?[] args) + - Extensions: manager.RaiseAddonCallback() (uses caller member name), manager.RaiseAddonCallbackFrom(MethodBase, ...) + +Common convenience behaviors +- [AddonCallback] without a name uses the method name as the event name. +- Callback parameter injection supports AddonContext, IServiceProvider (when compatible), and AddonManager automatically. +- RegisterHostApi also scans static methods/fields/properties for attributes on the provided type for convenience. + +Build and run (example) +- Build SampleAddon +- Copy SampleAddon/bin/Debug/net8.0/SampleAddon.dll to HostApp/Plugins +- Build and run HostApp +- Press T to raise the OnTick event; see SampleAddon reacting in the console. + +Notes +- Only assemblies that include [assembly: Addon(...)] and contain a non-abstract AddonBase implementation are loaded as addons. +- Non-addon DLLs in the Plugins directory are ignored. \ No newline at end of file