esx_christmas

esx_christmas is a seasonal ESX Legacy resource that spawns a landmark and a few presents at a configured location on a timer. Players walk up to a present, press E and receive cash and items depending on how early they opened it. It lives in the separate ESX-Legacy-Seasonal repository, not in [esx_addons].

OverviewCopy Anchor Link

The manifest only lists es_extended under dependencies, but it loads @ox_lib/init.lua as a shared script. Start ox_lib before this resource, see ox_lib.

InstallationCopy Anchor Link

Copy esx_christmas into your resources folder and start it after its dependencies:

ensure ox_lib
ensure es_extended
ensure esx_textui
ensure esx_christmas

The resource streams its own props (stream/*, with this_is_a_map 'yes' and a .ytyp file), so no extra map resource is needed.

How it worksCopy Anchor Link

1. A server thread calls StartCycle immediately on start and then every Config.EventInterval seconds.
2. A cycle first clears the previous locations (if DespawnLocationOnCycleEnd is on), then picks Config.MaxLocationsPerCycle entries from Config.Locations, randomly when UseRandomLocation is on, and broadcasts them to all clients.
3. Each client spawns the landmark, an optional hint prop and one present prop per PresentCoords entry as local, non-networked objects. A present shows the text UI "Press E to open the present" within 2.0 units.
4. Pressing E sends esx_christmas:server:claim. The server validates the claim, picks the reward tier from the claim order at that location and pays the player.
5. All clients get the claim notification, the present disappears and, when every present at a location is taken, the whole location is removed.

ConfigurationCopy Anchor Link

All keys are in config/main.lua.

LocationsCopy Anchor Link

Config.Locations = {
  {
    Name = "Legion Square",
    LandmarkCoords = vec3(203.525284, -941.169250, 29.55),
    LandmarkModel = "sp_medium_christmas_santa",
    PresentCoords = {
      vec3(199.437363, -935.485718, 29.678345),
      vec3(199.318680, -953.432983, 29.088623),
      vec3(175.002197, -950.268127, 29.088623),
    },
    HintModel = "sp_christmas_snowman"
  }
}

A hint model only shows its floating text when it has an entry in Config.Hints, which maps the model name to a locale key (xmas_hint_snowman, xmas_hint_deer ship by default).

PropsCopy Anchor Link

Config.Props lists the model names the resource may use: LandmarkModels, PresentModels (picked randomly per present), HintModels and ExtraDecorModels. The shipped names (sp_*, prop_xmas_*) come from the files in stream/. In the current code only LandmarkModels (server, random landmark) and PresentModels (client, random present) are read. HintModels and ExtraDecorModels are not used anywhere, so a hint prop comes from HintModel in the location. Custom models you add must be streamed by this or another resource.

Tiers and rewardsCopy Anchor Link

Config.Tiers = {
  {
    Name = "Legendary",
    ClaimOrder = { 1 },
    Rewards = {
      { Type = "cash", Amount = 10000 },
      { Type = "item", Name = "armor",            Amount = 1 },
      { Type = "item", Name = "christmas_ticket", Amount = 1 }
    }
  },
  -- Epic: ClaimOrder = { 2 }, Common: ClaimOrder = { 3 }
}

The first present opened at a location pays the Legendary tier, the second Epic, the third Common. ClaimOrder lists the claim numbers a tier applies to, so { 3, 4, 5 } stretches a tier. Rewards use xPlayer.addAccountMoney(Config.Account, amount) for cash and xPlayer.addInventoryItem(name, amount) for item, see xPlayer.

EventsCopy Anchor Link

Client to server (both are validated on the server):

Server to client: setLocations, removeLocation, clearLocations, despawnPresent, onClaim, presentAlreadyClaimed, cannotClaim and notify, all prefixed with esx_christmas:client:. They only drive props and notifications.

Common issuesCopy Anchor Link

• Rewards do nothing or throw errors. The default item names are not defined in the official legacy.sql or addons. Add rows to the items table or change Config.Tiers, see Add items.
• Debug spam in the console. Config.Debug is true by default. Set it to false for production.
• Claim limits never reset. The global and per-player counters are only reset when a cycle clears the locations. With DespawnLocationOnCycleEnd = false they keep growing until a restart.
• No "Press E" prompt. The prompt uses ESX.TextUI, which only works while esx_textui is running. Without it the present can still be opened with E, but nothing is shown.
• Only English text. Only locales/en.lua ships. Add a file in locales/ for other languages.

RelatedCopy Anchor Link

• Addons overview
• xPlayer
• esx_textui
• Add items
• ox_lib

Frequently asked questions