@@ -18,8 +18,16 @@ The path is relative to `object_logic`; for example,
1818cannot escape into ` global_logic ` or ` packages ` . Omit the path to clear an
1919attachment.
2020
21- The closest ` Luaparent ` in an object's normal MUX parent chain supplies the
22- active module. Reload all attached modules and their dependencies atomically
21+ The ` [mux] ` settings ` default_thing_lua_parent ` , ` default_room_lua_parent ` ,
22+ ` default_exit_lua_parent ` , and ` default_player_lua_parent ` assign direct Lua
23+ parents to newly created objects of each type. Paths use the same
24+ ` object_logic ` -relative format as ` @lua/parent ` ; robots use the player default.
25+ Changing a default does not update existing objects. Clones preserve the
26+ source object's Lua parent (or its lack of one) rather than receiving the type
27+ default.
28+
29+ An object uses only the ` Luaparent ` attached directly to it. Lua modules are
30+ not inherited through other objects. Reload all attached modules and their dependencies atomically
2331with ` @lua/reload ` ; a failed reload leaves the current Lua state running.
2432Use [ ` @lua/check ` ] ( validating-and-reloading/ ) to validate every Lua module
2533before reloading.
@@ -31,16 +39,17 @@ and are treated as handled.
3139Restore the file or update ` Luaparent ` , then use ` @lua/reload ` to activate the
3240repair. ` @lua/reload ` itself remains atomic and rejects a missing attachment.
3341
34- When a Wizard uses ` @examine ` on an object, the output identifies its effective
35- Lua parent and attachment object , then lists its command patterns, events,
42+ When a Wizard uses ` @examine ` on an object, the output identifies its direct
43+ Lua parent, then lists its appearance functions, command patterns, events,
3644schedule names, message providers, and locks. Use ` @lua/viewparent <dbref> ` to
3745display that module's raw source, or ` @lua/viewparent <path>.lua ` to inspect an
3846object-logic module directly by path.
3947
4048## Module contract
4149
4250An object module returns a table with optional ` commands ` , ` events ` , ` locks ` ,
43- ` messages ` , and ` schedules ` tables.
51+ ` messages ` , and ` schedules ` tables, plus optional ` internal_appearance ` and
52+ ` external_appearance ` functions.
4453Command entries use native Lua patterns and a handler:
4554
4655``` lua
@@ -64,6 +73,25 @@ Object event functions use the native Lua event names listed below. Event names
6473are validated by ` @lua/check ` ; an unknown name or non-function value is an
6574error.
6675
76+ ## Custom appearances
77+
78+ ` internal_appearance(ctx) ` and ` external_appearance(ctx) ` may return a string
79+ to replace all native ` look ` output for the object. Returning ` nil ` or no value
80+ uses the native name, description, contents, and exits. An empty string is a
81+ valid override that displays nothing.
82+
83+ Rooms always use ` internal_appearance ` , including a Wizard looking at a room
84+ remotely. Other objects use the internal function when the viewer is physically
85+ inside the object and the external function otherwise. A successful override
86+ suppresses the native name, description, contents, exits, and transparent-exit
87+ continuation. The normal room look lock and ` on_describe ` event still run.
88+
89+ The context has the usual ` object ` , ` enactor ` , ` cause ` , and optional
90+ ` descriptor ` fields, plus ` appearance ` , whose value is
91+ ` internal_appearance ` or ` external_appearance ` . Runtime errors, invalid return
92+ types, embedded NUL bytes, and oversized strings are logged and fall back to
93+ the native appearance.
94+
6795## Object locks
6896
6997Define locks as functions in the module's ` locks ` table. The supported keys
@@ -186,7 +214,7 @@ messages come from the structured lock result or the native defaults.
186214Movement also invokes the applicable cross-location message providers, which
187215do not have corresponding events.
188216
189- Connection events run for the player's effective module, the master room and
217+ Connection events run for the player's attached module, the master room and
190218its contents, and the applicable zone object or zone-room contents. Both
191219receive ` ctx.descriptor ` . ` on_connect ` also receives boolean ` ctx.reconnect ` ;
192220` on_disconnect ` receives string ` ctx.reason ` and runs only for the final active
@@ -217,12 +245,12 @@ schedules = {
217245 name = " hourly_notice"
218246 cron = " 0 * * * *"
219247 handler = function (ctx )
220- -- ctx.scope == "object" and ctx.object is the effective object.
248+ -- ctx.scope == "object" and ctx.object is the attached object.
221249 end ,
222250 },
223251}
224252```
225253
226- A shared ` Luaparent ` runs each matching schedule once for every object that
227- inherits it. Use the wizard-only ` @lua/schedule ` command to inspect active
228- schedules and their effective objects.
254+ A shared module path runs each matching schedule once for every object directly
255+ attached to it. Use the wizard-only ` @lua/schedule ` command to inspect active
256+ schedules and their attached objects.
0 commit comments