Native Service Registration: Override Aether's Core Services

The mod kernel’s service registry is priority-ordered. By registering a service with a higher priority than Aether’s built-in implementation, your Native Mod becomes the active implementation for that service ID. Removing your registration automatically restores the next-lower-priority implementation.

API

Call context.registerService() inside onLoad:

context.registerService(
    id: String,
    description: String = "",
    priority: Int = 100,
    methods: List<AetherModServiceMethod>,
    handler: AetherModServiceHandler
)

AetherModServiceHandler is a fun interface with one suspend method:

suspend fun invoke(method: String, args: JSONObject): JSONObject

Parameter	Description
`id`	The service identifier (e.g. `"skills"`, `"state"`, or a custom string).
`description`	Optional human-readable description of the service (defaults to `""`).
`priority`	Higher value wins. Aether core services use a deliberately low priority. Defaults to `100`.
`methods`	The list of `AetherModServiceMethod` instances describing the methods this implementation handles.
`handler`	`AetherModServiceHandler` invoked with the method name and a `JSONObject` of arguments; returns a `JSONObject` result.

Priority rules

Aether core services use a deliberately low priority so that Native Mods can override them with a standard priority value. Use priority 500 to reliably override any built-in service. Removing your registration (by calling the returned cleanup lambda) restores the next-lower-priority implementation, which may be another mod’s registration or Aether’s built-in.

Example — overriding the skills service

The following mod registers itself as the active implementation of the skills service and returns an empty skill list:

MyNativeMod.kt

class MyNativeMod : AetherNativeMod {
    override fun onLoad(context: AetherNativeModContext) {
        context.registerService(
            id = "skills",
            priority = 500,
            methods = listOf(AetherModServiceMethod("list")),
        ) { method, args ->
            when (method) {
                "list" -> JSONObject().put("skills", JSONArray())
                else -> throw UnsupportedOperationException("Unknown method: $method")
            }
        }
    }
}

context.registerService() returns a cleanup lambda. Retain and call it yourself if you need to unregister the service at runtime; the current Native Mod manager does not invoke onUnload.

Built-in services

The following services are registered by Aether core:

`skills`

Method	Arguments
`list`	—
`getSelection`	—
`setSelection`	`ids`, `scope`, `session_id?`
`setSelected`	`skill_id`, `selected`, `scope`, `session_id?`

Valid scope values: current, default / global, both / current_and_default.

`state`

Method	Arguments
`get`	`path`
`transaction`	`operations`

You can expose entirely new services from a Native Mod — not just override existing ones. Other extensions discover them via aether.services.list() and invoke them via aether.services.invoke().

Overview

Script Mod API

UI Reference

Native Mods

Pi Extensions

Examples

Native Service Registration: Override Aether's Core Services

API

Priority rules

Example — overriding the skills service

Built-in services

`skills`

`state`

​API

​Priority rules

​Example — overriding the skills service

​Built-in services

​skills

​state

API

Priority rules

Example — overriding the skills service

Built-in services

`skills`

`state`