Arcturus-Morningstar-Extended/docs/wired_tools_reference.md

Wired Creator Tools (:wired) Reference

1. Scope

This document describes the current :wired tooling that was added across:

• Arcturus-Morningstar-Extended (server-side data, diagnostics, config)
• Nitro_Render_V3 (packet parsing and room/session metadata)
• Nitro-V3 (UI, monitor, inspection, previews, inline editing)

It focuses on:

• the Monitor tab
• the Inspection tab (furni, user, global)
• the wired_emulator_settings database table
• the formulas and thresholds behind the monitor statistics

---

2. High-level architecture

2.1 Data flow

Emulator -> Nitro_Render_V3 -> Nitro-V3

• The emulator computes room diagnostics and exposes extra room, furni, user, and monitor metadata.
• The renderer parses those packets and stores the values in room/session data objects.
• Nitro reads those values and renders them in the :wired UI.

2.2 Main files

• Emulator diagnostics:
  • Emulator/src/main/java/com/eu/habbo/habbohotel/wired/core/WiredEngine.java
  • Emulator/src/main/java/com/eu/habbo/habbohotel/wired/core/WiredRoomDiagnostics.java
  • Emulator/src/main/java/com/eu/habbo/messages/outgoing/wired/WiredMonitorDataComposer.java
• Renderer parsing:
  • Nitro_Render_V3/packages/communication/src/messages/parser/roomevents/WiredMonitorDataParser.ts
• Nitro UI:
  • Nitro-V3/src/components/wired-tools/WiredCreatorToolsView.tsx

---

3. Database configuration

3.1 New table

Wired configuration is now separated from emulator_settings into:

wired_emulator_settings (
  key,
  value,
  comment
)

Migration file:

• Database Updates/002_move_wired_settings_to_wired_emulator_settings.sql

The migration:

1. creates wired_emulator_settings
2. imports existing wired values from emulator_settings
3. inserts defaults for new monitor/diagnostic keys when missing
4. removes migrated wired keys from emulator_settings

3.2 Compatibility behaviour

The emulator still has a fallback read path:

• first it reads wired keys from wired_emulator_settings
• if a wired key is still missing there, it can still read it from the old emulator_settings

This allows safe rollout during migration.

3.3 Wired configuration keys

Key	Default	Purpose
wired.engine.enabled	1	Compatibility flag kept for old configs. Wired now runs through the new engine only.
wired.engine.exclusive	1	Compatibility flag kept for old configs. Wired now runs through the new engine only.
wired.engine.maxStepsPerStack	100	Maximum internal processing steps allowed for one stack execution.
wired.engine.debug	0	Enables verbose wired engine logging.
wired.custom.enabled	0	Enables legacy custom wired compatibility logic.
hotel.wired.furni.selection.count	5	Maximum furni count selectable/storable by wired boxes.
hotel.wired.max_delay	20	Maximum accepted wired delay value for delayed effects.
hotel.wired.message.max_length	100	Maximum length of wired/bot text fields.
wired.effect.teleport.delay	500	Delay in milliseconds used by wired teleports.
wired.place.under	0	Allows wired furniture placement under other items.
wired.tick.interval.ms	50	Global tick interval in milliseconds for repeater-style wired.
wired.tick.resolution	100	Legacy compatibility tick resolution value.
wired.tick.debug	0	Enables verbose logging for the tick service.
wired.tick.thread.priority	6	Java thread priority for the tick service.
wired.highscores.displaycount	25	Maximum wired highscore entries shown to the user.
wired.abuse.max.recursion.depth	10	Maximum recursive wired depth before execution stops.
wired.abuse.max.events.per.window	100	Maximum identical events allowed inside the abuse rate-limit window.
wired.abuse.rate.limit.window.ms	10000	Time window in milliseconds used by the abuse limiter.
wired.abuse.ban.duration.ms	600000	Room wired-ban duration in milliseconds after abuse detection.
wired.monitor.usage.window.ms	1000	Rolling window size used to calculate monitor usage.
wired.monitor.usage.limit	1000	Maximum usage budget allowed in one monitor window.
wired.monitor.delayed.events.limit	100	Maximum delayed wired events that may be pending in one room.
wired.monitor.overload.average.ms	50	Average execution threshold in milliseconds for overload tracking.
wired.monitor.overload.peak.ms	150	Peak execution threshold in milliseconds for overload tracking.
wired.monitor.overload.consecutive.windows	2	Consecutive overloaded windows required before EXECUTOR_OVERLOAD.
wired.monitor.heavy.usage.percent	70	Usage percentage threshold that contributes to MARKED_AS_HEAVY.
wired.monitor.heavy.consecutive.windows	5	Consecutive heavy windows required before the room is marked heavy.
wired.monitor.heavy.delayed.percent	60	Delayed queue percentage threshold that contributes to the heavy state.

---

4. Monitor tab

4.1 Statistics shown in the UI

The Monitor tab currently shows:

• Wired usage
• Is heavy
• Room furni
• Wall furni
• Delayed events
• Average execution
• Peak execution
• Recursion
• Killed remaining
• Permanent furni vars

4.1.1 Wired usage

Format:

usageCurrentWindow / usageLimitPerWindow

Source:

• server-side WiredRoomDiagnostics

Meaning:

• usageCurrentWindow = cost consumed in the current rolling monitor window
• usageLimitPerWindow = max allowed budget before EXECUTION_CAP

4.1.2 Is heavy

Format:

Yes / No

Source:

• server-side boolean from WiredRoomDiagnostics

Meaning:

• Yes if the room has crossed the heavy thresholds for enough consecutive windows

4.1.3 Room furni

Format:

(floor count + wall count) / roomItemLimit

Source:

• numerator: renderer room object counts
• denominator: server room item limit exposed in room/session data

4.1.4 Wall furni

Format:

wall count / roomItemLimit

Important note:

• there is no separate wall-only cap here
• the denominator is the same room furni limit exposed by the server

4.1.5 Delayed events

Format:

delayedEventsPending / delayedEventsLimit

Source:

• server-side WiredRoomDiagnostics

4.1.6 Average execution

Format:

averageExecutionMs + "ms"

Meaning:

• average execution time of sampled stacks inside the current monitor window

4.1.7 Peak execution

Format:

peakExecutionMs + "ms"

Meaning:

• highest sampled execution time inside the current monitor window

4.1.8 Recursion

Format:

recursionDepthCurrent / recursionDepthLimit

Meaning:

• current nested wired call depth vs the configured recursion cap

4.1.9 Killed remaining

Format:

killedRemainingSeconds + "s"

Meaning:

• remaining room cooldown while wired execution is temporarily halted by protection logic

4.1.10 Permanent furni vars

Format:

customVariableEntryCount / 60

Current meaning:

• the numerator is the total number of renderer-side entries stored inside RoomObjectVariable.FURNITURE_CUSTOM_VARIABLES
• the denominator 60 is currently a fixed UI denominator

This is currently renderer-side custom variable count, not a DB row count.

---

4.2 Cost model behind Wired usage

The current estimated stack cost is computed in the emulator.

4.2.1 Base formula

cost = 1
cost += number_of_conditions
cost += 2 for each selector effect
cost += 3 for each non-selector effect
cost += 4 extra for each delayed effect
cost += recursionDepth * 2
cost = max(1, cost)

4.2.2 Practical breakdown

Element	Cost
Base stack cost	1
Each condition	+1
Each selector effect	+2
Each regular effect	+3
Each delayed effect	+4 extra
Each recursion level	+2

4.2.3 Example

If a stack has:

• 2 conditions
• 1 selector
• 2 normal effects
• 1 delayed effect
• recursion depth 1

Then:

1
+ 2 conditions
+ 2 selector
+ 6 regular effects
+ 4 delayed effect extra
+ 2 recursion
= 17

That 17 is what is attempted against:

usageCurrentWindow + estimatedCost <= usageLimitPerWindow

If the result would exceed the budget, the engine records EXECUTION_CAP.

---

4.3 Heavy / overload calculations

4.3.1 Overload

A monitor window is considered overloaded when:

executionSamplesCurrentWindow > 0
AND (
  averageExecutionMs >= overloadAverageThresholdMs
  OR
  peakExecutionMs >= overloadPeakThresholdMs
)

After wired.monitor.overload.consecutive.windows consecutive overloaded windows:

• the room logs EXECUTOR_OVERLOAD

4.3.2 Heavy

A monitor window is considered heavy when at least one of these is true:

usagePercent >= heavyUsageThresholdPercent
OR
delayedPercent >= heavyDelayedThresholdPercent
OR
overloadWindow == true

Where:

usagePercent = round(usageCurrentWindow * 100 / usageLimitPerWindow)
delayedPercent = round(delayedEventsPending * 100 / delayedEventsLimit)

After wired.monitor.heavy.consecutive.windows consecutive heavy windows:

• the room is marked heavy
• the monitor logs MARKED_AS_HEAVY

---

4.4 Error / warning log types

The monitor currently supports:

• EXECUTION_CAP
• DELAYED_EVENTS_CAP
• EXECUTOR_OVERLOAD
• MARKED_AS_HEAVY
• KILLED
• RECURSION_TIMEOUT

Each log/history entry can carry:

• type
• severity
• amount/count
• latest occurrence
• reason/motivation
• trigger/source label
• trigger/source id

---

5. Inspection tab

5.1 Furni inspection

Current variables include:

• @id
• @class_id
• @height
• @state
• @position.x
• @position.y
• @rotation
• @altitude
• @wallitem_offset (wall items only)
• @type
• @dimensions.x
• @dimensions.y
• @owner_id
• dynamic flags:
  • @can_sit_on
  • @can_lay_on
  • @can_stand_on
  • @is_stackable
• extra teleport variable when relevant:
  • ~teleport.target_id

Editable fields:

• @state
• @position.x
• @position.y
• @rotation
• @altitude
• @wallitem_offset (wall items)

Important notes:

• floor moves are sent through wired-style movement flow/animation
• wall item updates use wall position recomposition
• booleans such as sit/lay/stand/stack come from items_base-derived metadata, not from FurnitureData.json

5.2 User inspection

Current variables include:

• @index
• @type
• @gender
• @level
• @achievement_score
• @position.x
• @position.y
• @direction
• @altitude
• @favourite_group_id
• @room_entry
• @room_entry.teleport_id
• @user_id / @bot_id / @pet_id

Dynamic flags/actions include:

• @is_hc
• @has_rights
• @is_owner
• @is_group_admin
• @is_mute
• @is_trading
• @is_frozen
• @effect
• @team_score
• @team_color
• @team_type
• @sign
• @dance
• @is_idle
• @handitems

Editable fields:

• @position.x
• @position.y
• @direction

5.3 Global inspection

Current variables include:

• @furni_count
• @user_count
• @wired_timer
• @teams.red.score
• @teams.green.score
• @teams.blue.score
• @teams.yellow.score
• @teams.red.size
• @teams.green.size
• @teams.blue.size
• @teams.yellow.size
• @room_id
• @group_id
• @timezone_server
• @timezone_client
• @current_time
• @current_time.millisecond_of_second
• @current_time.seconds_of_minute
• @current_time.minute_of_hour
• @current_time.hour_of_day
• @current_time.day_of_week
• @current_time.day_of_month
• @current_time.day_of_year
• @current_time.week_of_year
• @current_time.month_of_year
• @current_time.year

Important notes:

• @timezone_server comes from the emulator room/session snapshot and follows hotel.timezone
• @timezone_client comes from the browser
• @wired_timer is currently client-side time since room entry
• @current_time.* is currently based on the server hotel time snapshot plus client-side progression

---

6. UI behaviour notes

6.1 Monitor windows

The monitor now uses real Nitro card windows for:

• info
• log history
• error information

This means they are:

• closable with the standard Nitro card close button
• draggable
• resizable

6.2 Keep selected

In Inspection:

• when Keep selected is enabled
• clicking another furni/user does not replace the current preview/selection

6.3 Inline editing

Inline editors:

• can be opened by clicking the row
• submit on Enter
• stop accidental room chat typing while the input is focused

---

7. Current limitations

• Permanent furni vars currently uses a fixed denominator (60) in the Nitro UI
• @wired_timer is still client-side, not a dedicated server timer
• wired.tick.resolution is kept for compatibility/documentation, but the current tick service uses wired.tick.interval.ms
• wired.highscores.displaycount is migrated/documented, but its usage should be validated in the current runtime path if highscore behaviour is changed later