Configuration Files

Two YAML files steer behaviour: config.yml (global limits, tax, enabled groups) and categories.yml (category layout for the listing menu).

`config.yml`

time-to-live: "14d"
sell-tax: 0.10

commands-enabled-groups:
  - "spawn"

listing-limits:
  default: 1
  roturier: 2
  empereur: 22
  divin: 23
  ah.arcane: 20
  ah.celeste: 25
  ah.mystique: 30

blacklisted-materials:
  - BEDROCK
  - BARRIER
  - COMMAND_BLOCK
  - STRUCTURE_BLOCK
  - JIGSAW
  - DEBUG_STICK
  - KNOWLEDGE_BOOK
  - LIGHT
  - END_PORTAL
  - END_GATEWAY
  - NETHER_PORTAL

Field	Type	Description
`time-to-live`	Duration	How long a listing stays in `LISTED` before the background task moves it to `EXPIRED`. Default `14d`.
`sell-tax`	double	Fraction of the listing price withdrawn from the seller on `/ah sell`. `0.10` = 10%. Refunded if listing fails.
`commands-enabled-groups`	`Set<String>`	AstralCore server-group names where `/ah sell` is allowed. Players on other groups can still browse and buy.
`listing-limits`	`Map<String, Integer>`	Per-permission cap on concurrent active listings. The highest matching entry wins; `default` is the floor for anyone with no other match.
`blacklisted-materials`	`List<Material>`	Bukkit material names. Trying to list any of these triggers `BLACKLISTED_ITEM`.

Listing limits

The limit lookup walks the player's permissions and picks the largest matching value:

maximumListings(player) = max { value for (perm, value) in listing-limits
                                if player.hasPermission(perm) }
                       ?? listing-limits["default"]

That means a tiered ladder works out of the box. Grant ah.arcane to a VIP and they automatically get 20 slots; promote them to ah.mystique and they get 30. Negative values are not supported.

Blacklist

Items are matched by Material only — variants of the same material are blocked together. To block a custom item (CraftEngine, AstralItems, …) by key, extend the model via the API; the built-in blacklist is intentionally narrow because the goal is to keep technical / debug items off the market, not to police gameplay.

`categories.yml`

Categories shape the browse experience. Each category occupies a slot in the listing menu and owns a list of materials; the matcher picks the first category whose materials set contains the item being filtered.

categories:
  ranks:
    id: "ranks"
    slot: 2
    fallback: false
    display:
      material: DIAMOND
      name: "<aqua>Ressources"
      lore:
        - "<gray>Ores, logs, crafting materials."
    materials:
      - DIAMOND
      - IRON_INGOT
      - GOLD_INGOT
      - OAK_LOG

  tools:
    id: "tools"
    slot: 3
    display:
      material: DIAMOND_PICKAXE
      name: "<yellow>Outils"
    materials:
      - DIAMOND_PICKAXE
      - NETHERITE_PICKAXE
      - FISHING_ROD

  # ...

  other:
    id: "other"
    slot: 10
    fallback: true
    display:
      material: CHEST
      name: "<gray>Divers"
    materials: []

Fields

Field	Type	Description
`id`	String	Internal identifier. Used by `%category_id%` and by the `category` column on the `items` row.
`slot`	int	Menu slot in `listing.yml` where the category icon appears.
`fallback`	boolean	Exactly one category must be `true`. Items whose material does not match any explicit category land here.
`display`	`ItemStackWrapper`	Standard AstralCore item — material, MiniMessage name, lore, model data, …
`materials`	`List<ItemStackWrapper>`	The materials (vanilla and custom) this category catches. Empty for the fallback.

Matching logic

find(itemStack):
  for category in categories where !category.fallback:
    if any of category.materials are similar to itemStack:
      return category
  return categories.find(fallback) or throw

The "similar" check goes through AHUtils.areSimilar — a deep equality that respects custom-item suppliers from AstralItems / AstralPets / AstralScrolls. See Averaging for the related itemKey logic, which determines how items are grouped for price averaging.

`database.properties`

A standard JDBC properties file copied from the JAR. It reuses the connection model from AstralCore — see the AstralCore database docs.

Last modified: 25 July 2026