zones.yml

zones.yml is where your zones live. A zone declared here can be started with /sh start <id> and stopped with /sh stop <id>, by a player or from the console, which is what lets schedulers and event plugins drive it.

After editing by hand, run /sh reload, then /sh info <id> to see what SomaHider actually read.

The smallest zone that works

Four fields. Everything else is optional.

zones:
  arena:
    world: events
    center:
      x: 1500
      z: 1500
    radius: 150

A zone using everything

zones:
  kothjapon:
    world: events
    center:
      x: 1500
      z: 1500
    radius: 150
    duration: 30m
    max_duration: 1h
    schedule:
      - days: [friday, saturday]
        start: '21:00'
        stop: '22:30'
    triggers:
      start_on_chat: '&6&lKoTH &f* The &7Japan &fKoTH has begun!'
      stop_on_chat: '&6&lKoTH &f* The &7Japan &fKoTH is over\.'
    reveal:
      - type: same_placeholder
        placeholder: "%factionsuuid_faction_name%"
        disguise:
          name: {value: '%factionsuuid_faction_name%'}
          skin: '%factionsuuid_faction_leader%'
    disguise:
      show_armor: false

The id

The key of the section is the zone id, and it is what every command takes.

Rule	Detail
Characters	`a-z`, `0-9`, `_` and `-`. Uppercase is lowered for you.
Length	1 to 32 characters.
Not allowed	An id made only of digits, or one already used by another zone.

A rejected id means the whole zone is skipped, and the reason is logged.

Position

Key	Required	Value
`world`	Yes	Name of the world. The zone will not start while that world is unloaded.
`center.x`	Yes	Block coordinate of the centre.
`center.z`	Yes	Block coordinate of the centre.
`radius`	Yes	1 to 512 blocks.

There is no y and no height limit. The zone is a circle on x and z, so it covers every height at once.

Duration

Key	Value
`duration`	How long a run lasts by default. Omit it to run until stopped.
`max_duration`	Ceiling for this zone, whatever duration is asked for. `none` removes the ceiling.

Durations are written like 20m, 1h30m or 2h.

Three values decide when a run ends: what was asked for (from /sh start <id> <duration>, or the zone’s own duration), the zone’s max_duration, and default_max_duration from config.yml when the zone sets no ceiling. The run lasts the shorter of the requested duration and the ceiling that applies.

That last part catches people out: a zone with no duration and no max_duration still stops after two hours, because default_max_duration ships at 2h.

always_on

always_on: true

The zone starts with the server and stays up. SomaHider ignores duration, max_duration, schedule and triggers on such a zone, and logs that it did.

schedule

A list of weekly slots, checked against the server clock. See running a zone on a weekly schedule.

Field	Required	Value
`days`	Yes	List of day names, or `daily`. Three-letter forms accepted.
`start`	Yes	Time of day, quoted, like `'21:00'`.
`stop`	No	Time of day. A `stop` earlier than `start` means the next day.

A slot whose stop equals its start is rejected. Slots missed while the server was down are not replayed on boot.

triggers

Regular expressions matched against outgoing chat messages. See starting a zone from a chat message.

Field	Value
`start_on_chat`	Pattern that starts the zone.
`stop_on_chat`	Pattern that stops it.

At least one of the two is needed, or the block is ignored. Colour codes are written with &. A pattern with no colour code can be typed by a player in chat, and SomaHider warns about it on load.

reveal

A list of exceptions to the disguise, tried in order until one matches. See letting some players recognise each other.

Field	Applies to	Value
`type`	All	`permission`, `same_placeholder`, `match` or `relational`.
`node`	`permission`	The permission node the viewer must hold.
`placeholder`	The other three	A placeholder written `%expansion_params%`.
`equals`	`match`, `relational`	One value or a list. Values written `%...%` are resolved globally. Case is ignored.
`disguise`	All	Optional. A disguise shown instead of the real player when the rule matches.

A relational placeholder must start with %rel_.

disguise

Overrides the disguise from config.yml for this zone. Only the keys you write are overridden, the rest is inherited. Same keys as the global section, described in changing how hidden players look.

When a zone does not load

A bad zone is skipped and the rest of the file still loads, so one typo does not take down your other zones. SomaHider logs one line per problem, on startup and on every /sh reload, naming the zone and the field:

zones.yml: zones.arena: radius must be between 1 and 512
zones.yml: zones.arena: reveal[0] relational placeholders start with %rel_
zones.yml: zones.kothjapon: duplicate id

/sh reload reports the same problems in chat, and /sh info <id> marks a zone as broken when it could not be read at all.

Two mistakes account for most of these:

Symptom	Cause
A schedule slot is silently missing	The time was not quoted, so YAML read `21:00` as a number.
The zone loads but never triggers	The pattern lost its colour codes, or a `.` was left unescaped in a place that matters.