> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/configuration-and-administration/configuration-files.md). # Configuration files All ArcMenu settings, menus, assets, and generated files live under `plugins/ArcMenu/`. Knowing what each file and folder handles makes everyday configuration changes, resource management, and project backups straightforward. ## Directory structure | File or directory | Purpose | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.yml` | Global configuration for language, shortcuts, input modes, cursor settings, client playback optimizations, marketplace access, and update checks. | | `offset.yml` | Global screen distance and coordinate offsets for Touch mode and Mouse/Vision modes. | | `menus/` | YAML menu configurations containing frontend visual elements, backend click regions, and interaction actions. | | `images/` | PNG images, animated GIFs, mouse cursor textures (`images/mouse/`), and tooltip backgrounds used by menus. | | `templates/` | Reusable frontend component templates shared across multiple menus. | | `animations.yml` | Entry, switch, and exit transitions for normal menus, along with animation tracks for elements inside menus. | | `animations/` | Standalone menu animation files installed from ArcPack packages. | | `tooltip.yml` | Size, padding, position, and nine-slice background styling for hover tooltips. | | `languages/` | Language files for plugin messages and bundled sample text. | | `effects/` | Scene configurations and timeline files for Effect cutscenes. | | `effects/assets/` | OGG audio and NBS music files played during Effects. | | `packs/` | Locally imported or downloaded `.arcpack` files and installation records. | | `backup-menu/` | Automatic menu backups created before saving changes in the visual editor. | | `workspace-backups/` | Automatic workspace backups created before imports, installations, or deletions in the project manager. | | `generated/` | Automatically generated resource pack files, including the ZIP archive for manual distribution. | ## Core configuration (`config.yml`) `config.yml` holds the global runtime settings for the plugin, organized into functional sections. ### Language and shortcuts ```yaml language: default: zh_CN follow-player-locale: true shortcuts: shift-f: true close-on-shift-f: true close-on-space: true ``` * **`language.default`**: Set this to a language filename under `plugins/ArcMenu/languages/` without the file extension. It defaults to `zh_CN`, and both `zh_CN` and `en_US` are built in. Console messages and fallback messages for unmatched client locales use this language. * **`language.follow-player-locale`**: Accepts `true` or `false`. When set to `true`, messages sent to players automatically match the language selected in their Minecraft client. * **`shortcuts.shift-f`**: Accepts `true` or `false`. When `true`, pressing Shift+F (sneak + swap offhand) while no interface is open directly opens the menu configured with `main-menu: true`. * **`shortcuts.close-on-shift-f`**: Accepts `true` or `false` (default `true`). Controls whether players can press Shift+F to close an open normal menu or third-party application. This switch works independently of `shift-f`, so you can disable opening the main menu with Shift+F while still letting players press Shift+F to exit an open menu. * **`shortcuts.close-on-space`**: Accepts `true` or `false` (default `true`). Controls whether pressing the jump key (Space by default) closes the active menu or application. Both closing shortcuts apply only to normal runtime menus and applications; they will not interrupt the visual editor, Arcitx text input, or Effect cutscenes. ### Input modes and mouse cursor ```yaml mouse: policy: player-choice default: touch assume-resource-pack-loaded: true sample-rate: 40 cursor: interpolation-ticks: 0 sensitivity-x: 2.0 sensitivity-y: 2.0 clamp-margin: 3.0 size: 5.0 z: 5.0 ``` * **`mouse.policy`**: Controls which interaction modes the server allows. Valid values are: * `player-choice`: Lets players switch freely between `touch`, `mouse`, and `vision` using `/arcmenu mode` (legacy names `crosshair` and `cursor` are also accepted). * `force-touch`: Locks the entire server to Touch mode (also accepts the legacy name `force-crosshair`). * `force-mouse`: Requires cursor-based interaction (also accepts `force-cursor`), supporting Mouse mode as well as Vision mode for players who have the matching ArcMenu Editor client mod installed. * **`mouse.default`**: Sets the initial mode for players joining the server before they choose a mode themselves. Accepts `touch`, `mouse`, or `vision`. Vision requires the matching ArcMenu Editor mod for the player's game version. * **`mouse.assume-resource-pack-loaded`**: Boolean (`true` or `false`), defaulting to **`true`**. * When **`true`**, ArcMenu trusts that the client already has the companion ArcMenu resource pack loaded and immediately enables Mouse mode flat lighting, menu depth, fixed FOV, the local client cursor, and eligible local GIF playback without waiting for a server resource-pack load receipt. This is ideal when players place the generated resource pack into their client's `resourcepacks` folder manually. * When **`false`**, ArcMenu waits until the server receives confirmation that the resource pack finished loading before enabling those Mouse features. If the resource pack is not ready while a menu is running, Mouse menus that rely on those features close cleanly and can be reopened once loading completes. * Regardless of this setting, clients need the matching ArcMenu resource pack installed. This option affects only Mouse mode and has no effect on Touch mode, Vision mode, standalone editor previews, or Effect playback. * **`mouse.cursor.sensitivity-x` / `sensitivity-y`**: Numbers from `0.05` to `50` (both default to `2.0`) that set the base horizontal and vertical cursor sensitivity. * **`mouse.cursor.clamp-margin`**: A number greater than or equal to `0` (default `3.0`) that defines how far past the canvas edge the cursor is allowed to move. * **`mouse.cursor.size`**: A positive number (default `5.0`) setting the logical height of the cursor on the canvas. Cursor textures are always read from `images/mouse/mouse.png` (default state) and `images/mouse/choose.png` (hovering over a clickable region). * **`mouse.cursor.z`**: A number (default `5.0`) setting the cursor's Z-axis depth so it stays in front of menu elements. * **`mouse.sample-rate`** and **`mouse.cursor.interpolation-ticks`**: Used by the legacy packet-driven cursor when a local client cursor is not active. `sample-rate` accepts an integer from `20` to `60` (default `40`) for samples per second, and `interpolation-ticks` accepts `0`, `1`, or `2` (default `0`) for smoothing ticks. Both the local Mouse cursor and the Vision cursor render directly on the client in real time without packet polling. ### Client playback and marketplace ```yaml client-playback: local-gifs: true linear-offsets: true marketplace: url: 'https://market.myarc.icu:10051' certificate-sha256: '' ``` * **`client-playback.local-gifs`**: Accepts `true` or `false` (default `true`). When enabled, eligible GIFs in Mouse mode play directly through native client animated textures with zero per-frame packets sent from the server. * **`client-playback.linear-offsets`**: Accepts `true` or `false` (default `true`). When enabled, eligible linear movement segments in animation timelines are handed off to vanilla display-entity interpolation on the client for smoother motion and lower bandwidth usage. * **`marketplace.url`**: The HTTPS URL for the menu marketplace (default `'https://market.myarc.icu:10051'`), used for browsing in the visual editor and downloading ArcPacks on the server. Leave it empty (`''`) to disable remote marketplace requests; local development and testing also accept `http://127.0.0.1:`. * **`marketplace.certificate-sha256`**: When running a self-hosted private HTTPS marketplace without a public CA certificate, enter the certificate's SHA-256 fingerprint here. Leave it empty (`''`) when using the official marketplace. For more details on these features, see [Touch, Mouse and Vision input](/en/feature-configuration/input-modes.md), [Animated GIFs](/en/feature-configuration/gif.md), and [ArcPack and marketplace](/en/feature-configuration/arcpack.md). ### Usage metrics and update notifications ```yaml metrics: enabled: true update-check: enabled: true url: 'https://market.myarc.icu:10051/arcmenu/updates/premium.json' notify-on-join: true ``` * **`metrics.enabled`**: Accepts `true` or `false` (default `true`). Controls anonymous bStats metrics (service ID **34690** for Premium and **34691** for Community). The global switch in `plugins/bStats/config.yml` is also respected. * **`update-check.enabled`**: Accepts `true` or `false` (default `true`). When enabled, the server periodically checks the public version manifest in the background (every 6 hours by default) to see if a newer release is available. Update checks only compare and report version numbers; they never download or replace plugin files automatically. * **`update-check.url`**: The JSON URL for the version manifest. Keep the default value. * **`update-check.notify-on-join`**: Accepts `true` or `false` (default `true`). When enabled, administrators with `arcmenu.admin` receive a notification upon joining if a newer version has been detected. Administrators can also run `/arcmenu update` at any time to check manually. ## Applying changes and rebuilding resources Saving a menu in the visual editor applies your changes to the server immediately. If you edit YAML menu files, `animations.yml`, or `config.yml` by hand, run `/arcmenu reload` after saving. When you add or modify PNGs, GIFs, tooltip textures, cursor settings, or templates under `images/` or `templates/`, rebuild the resource pack: 1. Run `/arcmenu resources` or `/arcmenu reload all` to rebuild ArcMenu's assets. 2. If your server uses a custom item plugin to merge and distribute packs, run its pack reload command: * **CraftEngine**: `/ce reload pack` (or `/ce reload all`) * **Nexo**: `/nexo reload pack` * **ItemsAdder**: `/iazip` 3. If you do not use those plugins, distribute the generated ZIP archive directly from `plugins/ArcMenu/generated/`. ## Automatic config completion and initial sample files Whenever ArcMenu starts or reloads, it checks `config.yml` and automatically fills in any missing default keys introduced by newer releases while preserving all of your existing values (including explicit `false`, `0`, empty strings, and empty lists), custom keys, and comments. On a fresh installation, ArcMenu Premium extracts a ready-to-use set of sample menus and resources: the `main` menu, the `start` onboarding menu, the `cursor-setting` personal cursor and sensitivity menu, a complete set of `shop/` category menus, the `teleport` menu, and three random-teleport Effect cutscenes (`rtp-overworld`, `rtp-nether`, and `rtp-end`), along with the `images/arcmenu.gif` intro animation and `animations.yml` tracks. Text in the sample menus references language files through `%arcmenu_lang_samples.%`, switching automatically between English and Chinese based on your server and player locale settings. The two mouse cursor textures are kept permanently as core runtime assets. These sample files are extracted only during the initial installation. If you delete sample menus, images, templates, or animations you do not need, future restarts, reloads, and plugin upgrades will respect your deletions and will not recreate them. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.myarc.icu/en/configuration-and-administration/configuration-files.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.