# 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.