ExilProductions/AddonLib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Readme

Browse Source
This commit is contained in:
Exil Productions
2025-09-08 22:26:40 +02:00
parent 3e8b70f869
commit 00249b265a
1 changed files with 97 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
README.md
View File

@@ -1 +1,97 @@
# 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.