ARTraveler v1.0

English:

ARTraveler is an innovative Traveling Merchant system for the ARStore universe. Unlike fixed shops (such as ARChestShop), this system creates dynamic events focused on scarcity and exclusivity. Traveling NPCs appear randomly across your server and disappear just as quickly as they arrived!

• Magical & Volatile NPCs: Travelers spawn and despawn using the Citizens API, but with a unique twist: a 100% memory-based registration. This prevents HD overcrowding and ensures zero persistence errors (ghost NPCs).
• Real Volatility: If an item runs out, it displays a visual "Sold Out" status. If all items for a specific visit are sold, the NPC leaves the area early.
• Exclusive Variation: Both prices and stock quantities fluctuate with every respawn. You never know if diamonds will be 20% more expensive or 10% cheaper today!
• Multi-Economy (Cash vs. Coins): Charge Vault for golden apples or require Cash (via AREconomy/PlayerPoints) for a Legendary Sword—all within the same menu.
• Hybrid Spawn System: Define multiple coordinates (Locations), and the traveler will randomly select one to appear. If you use classic Citizens, you can even use landmarks (e.g., "City Center").

---

How to Create and Manage Travelers​

Unlike a sign-based shop, a traveler must be configured and orchestrated by an administrator.

For Administrators (Initial Setup):​

1. Open the ARTraveler folder and edit the config.yml file.
2. Add a new "traveler" under the travelers section (you can copy the "test" example and rename it).
3. Specify the items to be sold, their price, and the chosen economy.
4. Save the file and run /artraveler reload in-game.
5. Go to the map locations where you want the NPC to spawn and type /artraveler set (name) at each spot. The plugin will randomly choose between these locations!

For Players (Rare Market):​

1. Players monitor the chat for server broadcast messages: "Traveler [Name] has arrived at (x, y, z)!"
2. Players must race to the NPC before the configured timer (e.g., 10 minutes) runs out.
3. Right-click the NPC to access the exclusive stock of that visit.
4. Everything is First-Come, First-Served. Once it's gone, it's gone!

---

Pro-Tips and Technical Setup​

• Compatible Economy: ARTraveler supports Vault and Cash systems! We highly recommend using AREconomy. Always fill the currency: field of your items with the created currency ID (e.g., cash, token, VAULT, PLAYERPOINTS).
• RNG Variation: Experiment with variation fields in the YAML file. If you use stock_variance_percent: 50.0, an item with a base_stock: 10 might appear with only 5 units in stock. This makes rare items highly coveted!
• Layout (GUI): The traveler's inventory size adjusts automatically based on the lines provided in the layout: list. Up to 6 rows are supported.

---

Commands and Permissions​

All commands require administrative permissions. They are designed for simple and direct control by the owner:

Note: To use these commands, you must first create the traveler IDs within your config.yml.

Click to expand...

Permissions​

The system is designed as a server-wide event; therefore, permissions are almost exclusively focused on Administrators.

Funcionalidades Principais​

O ARTraveler é um sistema inovador de Mercadores Viajantes para o universo ARStore. Diferente das lojas fixas (como o ARChestShop), este sistema cria eventos dinâmicos focados em escassez e exclusividade. NPCs viajantes aparecem aleatoriamente no seu servidor e desaparecem tão rápido quanto chegaram!

• NPCs Mágicos e Voláteis: Viajantes spawnam e despawnam utilizando a API do Citizens, mas com um diferencial incrível: um registro 100% em memória. Isso evita superlotação do seu HD e garante zero erros de persistência (fantasmas).
• Volatilidade Real: Se um item acabar, ele esgota no formato "Sold Out" (visual). E se todos os itens da visita esgotarem, o NPC vai embora antecipadamente.
• Variação Exclusiva: Tanto os preços quanto a quantidade de estoque de cada visitante flutuam com cada respawn. Você nunca sabe se o diamante hoje estará 20% mais caro ou 10% mais barato!
• Multi-Economia (Cash vs Coins): Cobre VAULT por maçãs douradas ou exija a tag cash (usando AREconomy/PlayerPoints) para comprar uma Espada Lendária, tudo dentro do mesmo menu.
• Sistema Híbrido de Spawn: Defina várias coordenadas (Locations) e o viajante sorteará uma delas para aparecer. Caso jogue com o Citizens clássico, pode até usar pontos de referência (ex: "Centro da Cidade").

---

Como Criar e Gerenciar Viajantes?​

Diferente de um Shop de placa, o viajante deve ser configurado e orquestrado por um administrador.

Para Administradores (Setup Inicial):

1. Abra a pasta do ARTraveler e edite o arquivo config.yml.
2. Adicione um novo "traveler" sob a sessão travelers (Você pode copiar o exemplo test e renomear).
3. Especifique os itens que ele venderá, a qual preço e por qual economia.
4. Salve o arquivo e use /artraveler reload no jogo.
5. Vá aos locais do mapa onde deseja que o NPC possa aparecer e digite /artraveler set (nome) em cada um. O plugin fará o sorteio entre esses locais!

Para os Jogadores (Mercado Raro):

1. O jogador acompanha o chat com a mensagem de broadcast do servidor: "O Viajante Fulano chegou em (x, y, z)!".
2. Os jogadores devem correr até o NPC antes que o tempo configurado (ex: 10 minutos) esgote.
3. Clique-direito no NPC para acessar o estoque exclusivo daquela visita.
4. Tudo é "First-Come, First-Served" (Primeiro a chegar, primeiro a levar). Acabou, acabou!

---

Dicas de Ouro e Setup Técnico​

• Economia Compatível: O ARTraveler suporta Vault e sistemas de Cash! Recomendamos plenamente o uso do AREconomy. Sempre preencha o campo currency: dos seus itens com a ID da moeda criada (ex: cash, token, VAULT, PLAYERPOINTS).
• Variação (RNG): Brinque com os campos de variação no arquivo YAML. Se você usar stock_variance_percent: 50.0, um item que tinha base_stock: 10 poderá aparecer apenas com 5 no estoque. Isso torna os itens raros altamente cobiçados na comunidade!
• Layout (GUI): O tamanho do inventário do viajante ajusta-se automaticamente e varia de acordo com as linhas passadas na lista layout: da config. Até 6 linhas suportadas.
  
  
  
• Todos os comandos exigem permissão administrativa. Eles são simples e diretos para o controle total do dono:
  
  

  Comando	Descrição
  /artraveler set (nome_do_viajante)	Cria um ponto de nascedouro para um viajante na sua localização atual.
  /artraveler spawn (nome_do_viajante)	Evoca imediatamente um viajante (bypassa o timer global).
  /artraveler despawn	Expulsa todos os viajantes atuais e fecha as lojas para seus jogadores.
  /artraveler reload	Recarrega instantaneamente as definições de items config.yml e messages.yml.

  Para usar estes comandos, você deve criar os IDs de viajantes dentro da sua config.yml (como no exemplo padrão: test).

  Click to expand...

• 
  O sistema é voltado principalmente a ser um evento do próprio servidor. Dessa forma, as permissões são quase que unicamente focadas nos Administradores.
  
  

  Permissão	Nível	Descrição
  Nenhuma Requerida	Jogador	Qualquer jogador pode interagir (Caminhar e clicar direito) nos viajantes visíveis.
  artraveler.admin	Administrador	Libera todos os 4 comandos de moderação do ARTraveler (/artraveler set, spawn, despawn e reload).