Letting some players recognise each other

A zone hides everyone from everyone, which is rarely what you want. In a faction event, players still need to tell their own side apart from the enemy. Otherwise they spend the fight hitting their own teammates.

A reveal rule is an exception to the hiding. You write them under reveal in the zone.

Start from what you want

You want	The rule to write
Teammates recognise each other	`same_placeholder` on a faction or team placeholder
Staff see everyone	Nothing. Give them `soma.hider.bypass` and let them use `/sh bypass`
One specific faction visible to all	`match` on a faction placeholder
Teammates shown under their faction name and colours	`same_placeholder` with a `disguise` block

Everything except the staff case needs PlaceholderAPI. Without it, SomaHider logs a warning for the zone and the players simply stay hidden.

Make teammates recognise each other

This is the one you will write most often.

Find a placeholder that returns the same value for two teammates.

With Factions that is usually %factionsuuid_faction_name%. Any placeholder works as long as two players on the same side get the same answer and two enemies do not.

Test it in game first with /papi parse me %factionsuuid_faction_name%.
Add the rule to your zone.
zones.yml
```
zones:
  kothjapon:
    world: events
    center:
      x: 1500
      z: 1500
    radius: 150
    reveal:
      - type: same_placeholder
        placeholder: "%factionsuuid_faction_name%"
```
Apply it.
```
/sh reload
```

Members of the same faction now see each other normally. Everyone else in the zone still sees them disguised.

The part that surprises people

A rule does not have to show the real player. It can show them as somebody else instead.

Add a disguise block to the rule, and the players it matches are shown under that second disguise rather than their real identity:

reveal:
  - type: same_placeholder
    placeholder: "%factionsuuid_faction_name%"
    disguise:
      name:
        value: '%factionsuuid_faction_name%'
      skin: '%factionsuuid_faction_leader%'

Teammates now see each other under the faction name, wearing the skin of their leader. Enemies still see the normal zone disguise. Nobody sees a real name at any point.

So a rule has two possible outcomes, and which one you get depends only on whether you wrote a disguise block:

The rule matches, and	The viewer sees
the rule has no `disguise`	The real player.
the rule has a `disguise`	That second disguise.
no rule matched at all	The normal zone disguise.

Reveal one specific faction

match compares a placeholder against a value you choose. The value can itself be a placeholder, which is what makes it follow the game:

reveal:
  - type: match
    placeholder: "%factionsuuid_faction_name%"
    equals: "%koth_faction%"

Whoever holds the KoTH right now is revealed to the whole zone, and the reveal moves on its own when the point changes hands.

equals also takes a fixed value, or a list of them:

reveal:
  - type: match
    placeholder: "%factionsuuid_faction_name%"
    equals: ["Fate", "Showry"]

Case does not matter in the comparison.

Give staff a way through

You can write a permission rule:

reveal:
  - type: permission
    node: myserver.staff

but for moderation, /sh bypass is usually the better answer. It is a toggle each staff member turns on and off themselves, it works in every zone at once, and it needs no configuration. Grant soma.hider.bypass and you are done.

Keep the permission rule for cases where a group must always see through one particular zone, whether they think about it or not.

When you write several rules

SomaHider reads the list from top to bottom and stops at the first rule that matches. That rule decides what the viewer sees, and the ones below it are not considered for that pair.

Put the specific rules above the general ones:

reveal:
  - type: match
    placeholder: "%factionsuuid_faction_name%"
    equals: "%koth_faction%"
  - type: same_placeholder
    placeholder: "%factionsuuid_faction_name%"

Check that it worked

/sh info kothjapon

The rules that were read appear in the zone details. A rule that is missing there was rejected, and the reason is in the server log:

zones.yml: zones.kothjapon: reveal[0] type is required (permission, same_placeholder, relational, match)
zones.yml: zones.kothjapon: reveal[1] placeholder must look like %expansion_params%

The number in brackets is the position in your list, counting from zero.