init

2026-05-26 23:20:08 -04:00
commit 4361d33ec3
56 changed files with 4508 additions and 0 deletions
@@ -0,0 +1,107 @@
+# Configuration
+
+## Location
+
+`<plugin data dir>/config.json`. Written with defaults on first boot.
+
+## Full config
+
+```json
+{
+    "tables": {
+        "friends": "social_friends",
+        "guilds": "social_guilds",
+        "guild_ranks": "social_guild_ranks",
+        "guild_members": "social_guild_members",
+        "guild_invites": "social_guild_invites",
+        "privacy": "social_privacy"
+    },
+    "channels": {
+        "friend_event": "social.friend",
+        "guild_event": "social.guild",
+        "guild_chat": "social.guild.chat",
+        "dm": "social.dm"
+    },
+    "guilds": {
+        "name_min_length": 3,
+        "name_max_length": 24,
+        "tag_max_length": 6,
+        "max_members": 50,
+        "chat_prefix": "[G]"
+    },
+    "friends": {
+        "max_friends": 100,
+        "max_pending_requests": 25
+    },
+    "dms": {
+        "prefix_to": "[to {name}]",
+        "prefix_from": "[from {name}]"
+    }
+}
+```
+
+Permission gating doesn't live here. Each command checks a permission node (`networksocial.<command>`) via Hytale's `PermissionsModule`. Configure those in the Hytale server's own permission config - see [03_Commands.md](03_Commands.md#permissions).
+
+## Fields
+
+### tables
+
+| Field | Default | Meaning |
+|---|---|---|
+| `friends` | `social_friends` | Friend requests + accepted friendships. |
+| `guilds` | `social_guilds` | One row per guild. |
+| `guild_ranks` | `social_guild_ranks` | Per-guild rank ladder (each guild has its own ranks). |
+| `guild_members` | `social_guild_members` | One row per player, points to their guild and rank. |
+| `guild_invites` | `social_guild_invites` | Pending invites. |
+| `privacy` | `social_privacy` | Per-player privacy settings (DM, friend-request, guild-invite policies). |
+
+Change a name only if you really need to (e.g. table collision with another plugin) and you're prepared to migrate data.
+
+### channels
+
+| Field | Default | Meaning |
+|---|---|---|
+| `friend_event` | `social.friend` | Bus channel for friend-request / accept / remove notifications. |
+| `guild_event` | `social.guild` | Bus channel for guild lifecycle events (invite, member changes, ranks, MOTD, disband). |
+| `guild_chat` | `social.guild.chat` | Bus channel for guild chat messages. |
+| `dm` | `social.dm` | Bus channel for DMs. |
+
+Channels are plain Redis pub/sub. Don't share them with other plugins. If you run multiple Social plugin clusters against the same Redis (different networks), use different channel names so they don't cross-talk.
+
+### guilds
+
+| Field | Default | Meaning |
+|---|---|---|
+| `name_min_length` | `3` | Minimum characters in a guild name. |
+| `name_max_length` | `24` | Maximum characters in a guild name. Stored as `VARCHAR(32)` so don't push above 32. |
+| `tag_max_length` | `6` | Maximum characters in the optional guild tag (currently informational; not surfaced in chat). |
+| `max_members` | `50` | Hard cap on members per guild. `acceptInvite` and `invite` enforce this. |
+| `chat_prefix` | `[G]` | Visual prefix for every guild chat line. |
+
+Names must be alphanumeric plus `_` and `-`. Spaces and punctuation are rejected. This matches the single-token nature of Hytale commands - if you allow spaces, `/guild invite My Cool Guild` is unparseable.
+
+### friends
+
+| Field | Default | Meaning |
+|---|---|---|
+| `max_friends` | `100` | Cap on accepted friendships per player. Send fails with `LIMIT_REACHED` past this. |
+| `max_pending_requests` | `25` | Cap on outgoing-pending requests per player. Stops one player from spamming the system. |
+
+### dms
+
+| Field | Default | Meaning |
+|---|---|---|
+| `prefix_to` | `[to {name}]` | Format for the sender's local echo. `{name}` substitutes the recipient's username. |
+| `prefix_from` | `[from {name}]` | Format for what the recipient sees. `{name}` substitutes the sender's username. |
+
+## Environment variables
+
+None specific to Social. Database + bus secrets live in NetworkCore's env (`MYSQL_PASSWORD`, `NETWORK_AUTH_TOKEN`).
+
+## Setting up permissions
+
+1. In your Hytale server's permission config, grant the relevant `networksocial.*` nodes to whatever groups you want.
+2. Default groups (e.g. `Adventurer`) should typically get `networksocial.friend.use`, `networksocial.dm.use`, `networksocial.privacy.use`, `networksocial.guild.use`.
+3. `networksocial.guild.create` is the gate for *founding* a guild - you might restrict that to a paid rank or to specific roles.
+4. `networksocial.admin` is reserved for future server-side moderation tools (force-disband, force-leave, etc); not consumed in v1.
+5. Players need to reconnect for newly-granted permissions to apply.