-- GIZMOD MILESTONE API — QUICK 3RD-PARTY OVERVIEW

-- Gizmod exposes milestone functions through:
-- remote.call("gizmod", ...)
--
-- Recommended dependency:
-- "gizmod >= 1.0.60"

-- =========================================================
-- REGISTER A PERSISTENT MILESTONE
-- =========================================================

remote.call("gizmod", "milestone_register", {
id = "my-mod.some-achievement", -- unique stable ID
source_mod = "my-mod",

name = "Some Achievement",
description = "Optional description",

category = "achievement",

-- Optional custom announcement color.
-- Hex colors are supported.
color = "#ffd700",

-- Optional arbitrary SERIALIZABLE context.
-- No LuaEntity/LuaPlayer/LuaForce objects.
context = {
reward = 100,
difficulty = "hard"
}
})

-- =========================================================
-- COMPLETE A PERSISTENT MILESTONE
-- =========================================================

remote.call("gizmod", "milestone_complete", {
id = "my-mod.some-achievement",

-- Usually provide whichever applies:
player_index = player.index,
force_index = player.force.index,

-- Optional completion-specific plain-data context.
context = {
position = {
x = player.position.x,
y = player.position.y
}
}
})

-- A persistent milestone only completes once.
-- Its first successful completion emits:
--
-- gizmod.milestone-completed

-- =========================================================
-- REPEATABLE MILESTONE-STYLE ANNOUNCEMENT
-- =========================================================
--
-- Use this for events that may happen many times and should
-- look like milestones without permanently filling the
-- milestone registry.

remote.call("gizmod", "milestone_announce", {
id = "my-mod.loot-pickup",
source_mod = "my-mod",

name = "Loot collected",
description = "Picked up 200 iron plates",

category = "loot",
color = "#55dd55",

player_index = player.index,
force_index = player.force.index,

context = {
xp = 450,
contents = {
{ name = "iron-plate", count = 200 }
}
}
})

-- Every successful milestone_announce emits:

-- gizmod.milestone-announced

-- =========================================================
-- SUBSCRIBE TO MILESTONE EVENTS
-- =========================================================
--
-- Milestones use Gizmod's normal cross-mod Events API.

remote.add_interface("my-mod", {
on_gizmod_event = function(event)

if event.name == "gizmod.milestone-completed" then
  local m = event.payload

  -- Common fields include:
  -- m.id
  -- m.name
  -- m.description
  -- m.category
  -- m.color
  -- m.source_mod
  -- m.player_index
  -- m.force_index
  -- m.tick
  -- m.persistent
  --
  -- Producer-supplied extra data:
  -- event.context
end

if event.name == "gizmod.milestone-announced" then
  local m = event.payload

  -- Same general payload shape.
  -- event.context contains producer-defined data.
end

end
})

remote.call("gizmod", "event_subscribe", {
mod_id = "my-mod",
event = "gizmod.milestone-completed",
interface = "my-mod",
handler = "on_gizmod_event"
})

remote.call("gizmod", "event_subscribe", {
mod_id = "my-mod",
event = "gizmod.milestone-announced",
interface = "my-mod",
handler = "on_gizmod_event"
})

-- =========================================================
-- IMPORTANT
-- =========================================================
--
-- • IDs should be stable and namespaced to your mod.
-- • Only pass plain serializable Lua data in context.
-- • Do not pass LuaPlayer, LuaEntity, LuaForce, etc.
-- • milestone_complete = permanent/one-time milestone.
-- • milestone_announce = repeatable milestone-style message.
-- • Historical milestone sync during save migration does NOT
-- fire milestone-completed events retroactively.