Log inGet started
World

Treasure Trove: Coins, Hearts and Power-Up Pickups Kit

README.md

pickupsKit 2.3.14

Coins, gems, hearts, shields, keys, letters and power-ups for any game: one Pickup component, 47 looks in five styles, each tagged with its size, and multiplayer claims where a simultaneous grab has exactly one winner.

Built for platformers, arena shooters, kart racers and adventure games. Every pickup also has its own synthesised sound.

Guides

Two guides ship inside this package, in pickupsKit.package/guides/, and install with it. Open them from the Docs panel, or ask your agent for them by name:

  • How to add coins, gems and power-ups to my game: the how-to. What the kit is and what to do first, placing pickups, picking and swapping a look (one setting swaps it for every player), what each kind of pickup gives, pickups that come back or vanish with a blink, magnet pull, chests and coin bursts, what happens when several players go for the same pickup, reading and spending what a player collected, and scoring pickups with scoreKit.
  • Make a coin and gem collecting game with power-ups and respawning pickups: the example. From an empty world, a small game with a ring of coins, rubies, a speed power-up and a gem fountain where emeralds keep coming back, with every grab scored by scoreKit.

Both link the guides of the kits pickups go with. SecondWind's How to add health and damage to your game and juiceKit's How to add screen shake, hitstop and hit feedback to your game and Make your game feel juicy step by step with hit feedback, explosions and damage numbers come into your world with pickupsKit. scoreKit's How to add a score and combo system to my game and Make an arcade game with a score, combos and a leaderboard come with scoreKit, a separate install.

Install

One install: zeromind_install guid=0d70dd00-9297-45d5-a290-5a51b9f9e262, or search ZeroMind for "pickupsKit" and install it from the ZeroMind panel.

That one install also brings the kits pickupsKit builds on as its own dependencies under /source/deps/, each in its current release. Your world ends up with /source/pickupsKit.package and nothing else to set up. While the files land, the log can show passing lines such as waiting for content it requires or which is being fetched; they stop once the install is done.

Builds on

  • SecondWind 1.2.0 or newer (the "Second Wind" world): hearts, medkits and potions heal through it, shields top up its shield, and the damage and invincible power-ups go through its damage filter. SecondWind is itself built on Lifeline 1.0.1 and MatchFlow, which come along too. Installs in November 2026 brought SecondWind 1.3.1 and Lifeline 1.0.1, and MatchFlow 1.3.1 or 1.0.0: the MatchFlow release an install picks has varied from one day to the next, and both work with pickupsKit.
  • juiceKit 1.2.1 or newer (the "Juicebox" world): the sparkle, flash and pop when something is picked up, spawns or expires. pickupsKit 2.3.13 brings juiceKit 1.2.10.

pickupsKit 2.3.1 and 2.3.2 were checked against exactly those versions in a brand-new world, and 2.3.3 in this showcase world once it was updated to them: the quick start below, hearts healing, power-ups, and the kit's 86 tests.

Your own scripts can use these kits directly, require("SecondWind.api") and require("juiceKit.juice"), or go through pickupsKit: Pickups.health() returns SecondWind's api, Pickups.healthParts() its Rules, Health, HUD and Trap components, and Pickups.juice() juiceKit's effects. Both reach the same copy.

Pickups.dependencies() lists each kit with the version it needs, the version installed, whether it has loaded, and ok, which is true when the installed one is that version or newer.

Pickups never wait for these. The kit loads SecondWind and juiceKit the first time it needs them, not when it starts. If one is missing or still downloading (a web build fetches packages while the world opens), pickups still appear, spin, collect and count, and the counter and chests still work; the kit logs one warning and tries again a little later. A heart taken meanwhile is still collected, with note = "no health kit" on its collect event.

Quick start

Add these lines inside content() in your scene's build.luau, just before its closing end. A brand-new world already has one, scenes/main.scene/build.luau, with a ground, a sky and a player. (A world without a scene gets one from tools.use("scene", "create", "level", "player", { startup = true }); add the lines to scenes/level.scene/build.luau the same way.)

local Pickups = require("pickupsKit.api")

-- the coin counter in the corner of the screen
entity.spawn("PickupHUD").component.add(Pickups.HUD, { style = "pixel" })

-- five pixel gems in a line in front of where the player starts
for i = 1, 5 do
	Pickups.spawn({ (i - 3) * 1.5, 0, 4 }, { prefab = "pixelGem" })
end

Press Play and walk forward. Each gem you touch pops with a sparkle and a coin sound, and the counter adds 1. Each gem comes back 5 seconds later. The host makes the synced ledger that holds the counts by itself, so there is nothing else to place.

More examples

All of these go in content() too, after the quick start.

-- Health for players, so hearts and shields have something to heal.
local HK = Pickups.health()
entity.spawnSynced("HealthRules").component.add(HK.RULES, {})
HK.attach(body, { model = "shield" })   -- `body` is your PlayerPrototype's body entity

-- A heart that heals 25, a speed power-up and a key that never comes back.
Pickups.spawn({ -2, 0, 6 }, { prefab = "heart" })
Pickups.spawn({ 0, 0, 6 }, { prefab = "speedOrb", duration = 10 })
Pickups.spawn({ 2, 0, 6 }, { prefab = "silverKey", respawn = false })

-- Letter tokens that spell ZERO, one copy per player.
for i, l in { "Z", "E", "R", "O" } do
	Pickups.spawn({ -3 + i * 1.5, 0, 8 }, { prefab = "letterToken", letter = l, mode = "perPlayer" })
end

-- A chest that spills 12 rubies when a player walks up to it.
local chest = entity.spawnSynced("Chest", { position = { 0, 0, 11 } })
chest.component.add(Pickups.CHEST, { prefab = "ruby", count = 12 })

Hearts and shields heal only bodies that have SecondWind health, as above. Without it a heart is still collected, but it has nothing to heal. Pickups.health() is nil while SecondWind is still loading; in content() it has loaded.

To show a word's letters lighting up, give the HUD a word: { style = "cartoon", word = "ZERO" }.

Reading and spending from your own code (in a component or anything else that runs in play):

Pickups.on("collect", function(ev) print(ev.key, "took", ev.prefab, ev.amount) end)
if Pickups.spend(player, "coins", 10) then openDoor() end
print(Pickups.get(player, "keys"), Pickups.letters(player), Pickups.spelled(player, "ZERO"))

Switching a look is one setting, and it applies right away, for every player, also while the game runs:

pickupEntity.component.get(Pickups.PICKUP).prefab = "pixelGem"   -- on the engine that owns the pickup
Pickups.setPrefab(pickupEntity, "pixelGem")                       -- from any engine

The model is rebuilt on every engine as the change arrives. The pickup keeps its other settings. With effect = "auto" (the default) it now does what the new look does.

Who can write the setting. Like every synced setting, prefab can only be written by the engine that owns the pickup: the host for scene pickups, or whoever spawned it. Any other engine's write is refused by the engine on the spot and changes nothing, and the kit can't catch it. Pickups.setPrefab works from every engine: on the owner it writes the setting, and elsewhere it asks the owner to. Both were played with two players: a coin one player owned changed to pixelGem for both through the plain setting, and a gallery pickup the other player's engine owned changed through setPrefab called by the player who wasn't hosting. Old names worked the same way, through look = "cartoon_coin" and setPrefab(box, "cartoon_mystery").

Coin bursts from a defeated enemy or a broken pot:

Pickups.burst(enemy.position, { prefab = "goldCoin", count = 10, lifetime = 12 })

The coins fly out and bounce. Each one can only be taken once it has settled, and each blinks for its last 3 seconds before it disappears.

The Pickup component

pickupsKit.Pickup. Every setting is synced: a change made on the engine that owns the pickup reaches every engine, also while the game runs.

SettingDefaultWhat it does
prefabgoldCoinWhich of the 47 looks it wears, by its short name (the Looks table). This also sets what it does when effect is auto.
lookgoldCoinThe older name of prefab, kept so existing scenes and code keep working. It takes the new names and the old ids. Whichever of the two you write, the other follows.
effectautoWhat touching it does: auto, counter, heal, shield, item, letter, powerup, mystery or none.
amount0How much it gives: coins, health, shield and so on. 0 uses the look's amount.
counter""Counter for counter: coins, gems, stars, rings, xp, ammo, or any name of your own.
item""Item for item: keys, keycards, or your own. It is counted like a counter.
letter"A"The letter shown on letter tokens.
powerup, duration"", 0The power-up and its length in seconds: speed, jump, damage, magnet or invincible.
radius1.1How close a player must come to take it, in metres.
magnetRange0Within this range it flies to the player. 0 means no magnet. A magnet power-up triples it.
respawn, respawnTimetrue, 5Whether it comes back after being taken, and after how many seconds.
lifetime, blinkTime0, 3It disappears after lifetime seconds untouched (0 = never), blinking for the last blinkTime of them. With respawn on, it then comes back after respawnTime.
modesharedshared: the first player to touch it gets it. perPlayer: every player can take their own copy, and it comes back for each of them separately.
bob, spin, hover, scale0.12, 1.8, 0.6, 1Bob height in metres, spin in turns per second, hover height and size.
visibletrueHide it without removing it.
castShadowsfalseCast a sun shadow. Off by default, because many small spinning casters redraw the shadow map every frame, which costs most in a web browser. Turn it on for a few hero pickups.

available, taken, armed and launch are state fields that the kit writes itself.

Old names keep working. Every look had a longer id before 2.2.0 (cartoon_coin, real_gold_coin, pixel_gem_coin...), and six looks had other short names in 2.2: redHeart, speedCore, damageCore, jumpCore, xpShard and ammoBox are now heart, speedOrb, damageOrb, jumpOrb, xpOrb and ammoCrate. Every older name still works everywhere a look goes: the look setting, spawn, setPrefab, setLook, burst, chests and look(), and it is stored as the main name. The prefab field's own list holds only the main names, so writing an older name straight into prefab is refused by the engine; use look, or setPrefab. The Looks table shows every other name a look answers to, and looks() returns them as otherNames.

Other components:

  • PickupChest opens when a player comes within radius and spills count coins of any prefab (look is its older name there too). It closes again after cooldown seconds, or stays open if cooldown is 0. It draws its own chest model; set showModel = false to use yours.
  • PickupHUD is the on-screen counter, with style set to cartoon, scifi, fantasy, pixel or realistic. Its other settings:
    • counters: which counters it shows, in order;
    • word: a word whose letters light up as they are collected;
    • showPowerups: running power-ups with their time left;
    • showPlayers: every player's coins;
    • corner: which top corner it sits in.
  • PickupLedger is the synced record of every player's counters and letters. The host spawns it by itself.

Looks

There are 47 looks in five styles that a world can mix and match: cartoon 9, sci-fi 10, fantasy 10, pixel 9 and realistic 9. To list them, call Pickups.looks(), or filter with Pickups.looks({ style = "pixel" }), Pickups.looks({ kind = "coin" }) or Pickups.looks({ size = "small" }); filters combine. Each entry carries its id (the prefab name), oldId, name, style, kind, effect, size, sizeM, dims and what it gives.

StyleWhat it looks like
cartoonChunky glossy shapes with dark ink outlines.
scifiDark metal shells around glowing energy cores.
fantasyGems, potions in glass, gold and runes.
pixelVoxel sprites: 8-bit pixels with real depth.
realisticBrushed metal, brass, painted boxes and real-world props.

Sizes. Every look carries a size tag measured from its model at scale = 1. dims is its width, height and depth in metres, and sizeM is the largest of the three. Pickups.sizes() lists the tags:

SizeLargest sideLooks
smallup to 0.62 m9: gems, wisps, the realistic coins and kits
medium0.63 to 0.75 m28: most coins, hearts, keys, badges and pixel sprites
largeover 0.75 m10: power-up cores, potions, shields and the winged orb

Use the tag to pick looks that sit well together, or to choose a radius: about 1.1 suits small and medium looks, and about 1.3 suits large ones. pickupsKit.visual.extent(prefab) measures a model's box directly.

prefabAlso answers toNameStyleKindEffectSizeGives
goldCoincartoon_coinGold coincartooncoincountermedium (0.72 m)coins +1
goldStarcartoon_starStarcartoonstarcounterlarge (0.78 m)stars +1
goldRingcartoon_ringGold ringcartoonringcountermedium (0.72 m)rings +1
heartcartoon_heart, redHeartHeartcartoonhearthealmedium (0.68 m)heal 25
mysteryBoxcartoon_mysteryMystery boxcartoonmysterymysterymedium (0.65 m)random roll
letterTokencartoon_letterLetter tokencartoonletterlettermedium (0.70 m)its letter
speedBadgecartoon_speedSpeed badgecartoonpoweruppowerupmedium (0.70 m)speed 8s
damageBadgecartoon_damageDamage badgecartoonpoweruppowerupmedium (0.70 m)damage 8s
jumpBadgecartoon_jumpJump badgecartoonpoweruppowerupmedium (0.70 m)jump 8s
energyCreditscifi_chipEnergy creditscificoincountermedium (0.70 m)coins +1
shieldCellscifi_shieldShield cellscifishieldshieldlarge (0.77 m)shield 30
accessCardscifi_keycardKeycardscifikeycarditemmedium (0.64 m)keycards +1
ammoCellscifi_ammoAmmo cellscifiammocountermedium (0.72 m)ammo +30
speedOrbscifi_speed, speedCoreSpeed orbscifipoweruppoweruplarge (0.78 m)speed 8s
damageOrbdamageCore, scifi_damageDamage orbscifipoweruppoweruplarge (0.78 m)damage 8s
jumpOrbjumpCore, scifi_jumpJump orbscifipoweruppoweruplarge (0.78 m)jump 8s
magnetCorescifi_magnetMagnet corescifipoweruppoweruplarge (0.78 m)magnet 10s
xpOrbscifi_xp, xpShardXP orbscifixpcountermedium (0.66 m)xp +10
nanoMedkitscifi_medkitNano medkitscifimedkithealmedium (0.64 m)heal 50
rubyfantasy_rubyRubyfantasygemcountersmall (0.60 m)gems +1
emeraldfantasy_emeraldEmeraldfantasygemcountersmall (0.54 m)gems +3
healingPotionfantasy_potion_redHealing potionfantasypotionheallarge (0.76 m)heal 35
wardPotionfantasy_potion_blueWard potionfantasypotionshieldlarge (0.76 m)shield 35
goldenKeyfantasy_keyGolden keyfantasykeyitemmedium (0.69 m)keys +1
silverKeySilver keyfantasykeyitemmedium (0.69 m)keys +1
crestShieldCrest shieldfantasyshieldshieldlarge (0.81 m)shield 40
wingedOrbfantasy_jumpWinged orbfantasypoweruppoweruplarge (0.94 m)jump 8s
runeStonefantasy_runeRune stonefantasyletterlettermedium (0.67 m)its letter
xpWispfantasy_wispXP wispfantasyxpcountersmall (0.47 m)xp +25
pixelGempixel_gem_coinPixel gempixelcoincountermedium (0.72 m)coins +1
pixelCoinpixel_coinPixel coinpixelcoincountermedium (0.68 m)coins +1
pixelHeartpixel_heartPixel heartpixelhearthealmedium (0.68 m)heal 25
pixelKeypixel_keyPixel keypixelkeyitemmedium (0.70 m)keys +1
powerStarpixel_starPower starpixelpoweruppowerupmedium (0.72 m)invincible 8s
jumpMushroompixel_mushroomJump mushroompixelpoweruppowerupmedium (0.68 m)jump 10s
pixelSwordpixel_swordPixel swordpixelpoweruppowerupmedium (0.72 m)damage 8s
pixelLetterpixel_letterPixel letterpixelletterlettermedium (0.72 m)its letter
questionBlockpixel_mysteryPixel ? blockpixelmysterymysterymedium (0.63 m)random roll
silverCoinreal_silver_coinSilver coinrealisticcoincountersmall (0.60 m)coins +1
goldDoubloonreal_gold_coinGold doubloonrealisticcoincountermedium (0.64 m)coins +5
goldBarreal_gold_barGold barrealisticcoincountersmall (0.62 m)coins +25
cutDiamondreal_diamondDiamondrealisticgemcountersmall (0.60 m)gems +5
firstAidKitreal_medkitMedkitrealisticmedkithealsmall (0.62 m)heal 50
ammoCrateammoBox, real_ammoAmmo craterealisticammocountersmall (0.62 m)ammo +30
brassKeyreal_keyBrass keyrealistickeyitemmedium (0.69 m)keys +1
armorPlatereal_armorArmor platerealisticshieldshieldmedium (0.71 m)shield 50
energyDrinkreal_energyEnergy drinkrealisticpoweruppowerupsmall (0.60 m)speed 8s

Effects

EffectWhat it does
counterAdds amount to the player's counter.
healHeals amount through SecondWind (HK.heal), on the engine of the player who took it. A player at full health still takes it: the heart is collected and counted, and heals 0.
shieldTops up the SecondWind shield by amount, up to the maximum, on the engine that holds that player's health (the kit sends it there).
itemAdds amount of item (keys, keycards...). Spend it with Pickups.spend(player, "keys", 1).
letterAdds the token's letter. Check a word with Pickups.spelled(player, "ZERO").
powerupGives a timed power-up. Taking the same one again adds to its time.
mysteryRolls one weighted reward: coins, XP, heal, shield or any power-up.
noneNothing but the collect event, so you can handle it yourself.

Power-ups:

  • speed: moveSpeed ×1.6.
  • jump: jumpForce ×1.55.
  • damage: deals ×2 damage through SecondWind.
  • magnet: pickups pull from 3× further away.
  • invincible: takes no SecondWind damage.

Each family has a speed, damage and jump look: cartoon badges (speedBadge, damageBadge, jumpBadge), sci-fi orbs (speedOrb, damageOrb, jumpOrb), and the pixel jumpMushroom, pixelSword and powerStar.

Speed and jump are held on the player's CharacterController, on that player's own engine, for as long as the power-up runs. If something else, such as SecondWind's chill, changes the speed meanwhile, that change is respected.

Damage and invincible work through SecondWind's damage filter. Every engine knows every player's power-ups, so the filter is right wherever the damage is decided. The kit installs the filter the first time one of those power-ups is given, or straight away through Pickups.setup(). SecondWind keeps a single filter, so if your world has its own, call Pickups.setup({ damageFilter = false }) and multiply by Pickups.damageMultiplier(attacker, victim) inside yours.

API

local Pickups = require("pickupsKit.api"). A "player" argument can be an avatar entity, any collector entity, a peer number or a ledger key ("p3").

Pickups

  • spawn(pos, settings?, { synced = true, name }?) returns the entity. It errors on an unknown prefab or mode. settings.prefab names the look (settings.look is its older name).
  • burst(pos, { prefab, count = 8, amount, spread = 2.4, lifetime = 12, blinkTime = 3, magnetRange, mode, synced }) returns the coins.
  • setPrefab(pickup, prefab) (also setLook), collect(pickup, collector), available(pickup, collector?).
  • restore(target?) puts taken pickups back for a new round: one pickup, a list, or nil for every pickup in the scene. Returns how many it restored or asked the owner to restore.
  • all() returns { [id] = Pickup }. openChest(chest).

Counters

  • get(player, counter), counts(player), allCounts().
  • add(player, counter, n), set(player, counter, v), spend(player, counter, n), reset(player?).
  • ledger() returns the PickupLedger component in use.

Letters: letters(player), spelled(player, word), giveLetter(player, letter), clearLetters(player).

Power-ups: givePowerup(player, name, secs), powerup(player, name), powerupLeft(player, name), activePowerups(player), damageMultiplier(attacker, victim).

Catalog: looks(filter?) (filter by style, kind, effect and size), look(id) (a new name or an old id), styles(), kinds(), effects(), powerups(), counters(), sizes(). Everything they return is a copy.

The kits it builds on: dependencies() returns { name, needs, installed, loaded, problem, ok, why } for SecondWind and juiceKit. health() and juice() return each module, or nil and why not, loading it if it can. healthParts() returns SecondWind's { Rules, Health, HUD, Trap } components.

Identity: keyOf(x), nameOf(x), localKey(), localAvatar(), owns(x).

Checking every engine: peerReport(seconds?) asks every engine in the play session for its selfReport() and returns { [peer] = report }, this engine's own included. Each report says whether SecondWind and juiceKit loaded on that engine (and why not), which platform it runs on (native or browser), whether it holds the ledger, its own player's health as SecondWind sees it, and the outcome of the last heal or shield it applied. It is how a problem on another player's engine, such as a browser, can be read from yours.

Collectors: addCollector(entity) lets a bot or a kart collect, with its counts kept under "e<id>". removeCollector(entity) undoes it.

Setup: setup({ hud = true, hudStyle = "cartoon", word = "", damageFilter = true }) is optional. It makes the ledger now rather than after the host's first second, adds the HUD and installs the damage filter. installDamageFilter() installs just the filter.

Events, through on(event, fn), which returns an unsubscribe function:

EventArguments
collectev = { id (event id), p (pickup id), prefab, look (the same name), style, kind, effect, amount, counter, item, letter, powerup, duration, mystery, key, cid (collector id), pos, mode }
counterkey, counter, value, delta
letterkey, letter, letters
powerupkey, name, seconds
powerupEndkey, name
respawnpickupId
expirepickupId, pos
burstpos, count
chestchestId

pickupsKit.visual draws a look on this peer, for your own props or menus:

  • build(prefab, { letter, name, shadows }?) returns a handle;
  • place(h, pos, yaw, scale), setVisible(h, on), setShadows(h, on), alive(h), destroy(h);
  • extent(prefab) returns the model's { x, y, z } box at scale 1, or nil for an unknown look;
  • release(h) parks a visual hidden for reuse, and acquire(prefab, opts?) takes a parked one of that look back, or builds a new one. poolSize() and clearPool() look after the pool, which holds up to POOL_PER_LOOK (16) per look and POOL_MAX (96) in all.

pickupsKit.logic holds the rules as pure functions you can reuse or test: canClaim, applyClaim, settle, addCount, spelled, rollMystery, burstVelocity, stepCoin, magnetStep, blinkVisible, versionAtLeast and more. pickupsKit.catalog is the raw data: LOOKS, BY_ID, IDS, SIZES, REQUIRES, ALIASES (old id to new name), OLD_ID (new name to old id) and canonical(id), which turns any old id into the current name.

How multiplayer works

  • The owner decides. Every pickup is a synced entity, and the engine that owns it (the host, for scene pickups) is the only one that decides who gets it. Each engine runs the touch test for the players and collectors it moves, then asks the owner. The owner checks that the pickup is still available to that player and that the player is really within reach, then marks it taken in the same step, so when two players touch the same coin the first claim to arrive wins and it is counted once.
  • Entities travel as entities. The kit never relies on an entity's id string matching on another engine: pickups, chests and players go over the network as entity references, which each engine receives as its own, and become local ids on arrival. As a safeguard the kit also sends each entity's sync id, which every engine shares, and can resolve an entity from it if a reference ever arrives as raw data. (Before 2.2.0 the kit sent id strings, so a claim from a player who wasn't hosting named a pickup the host didn't know, and none of their pickups did anything.)
  • One announcement per collect. The owner announces the result as one event with an id. Every engine records the power-ups and plays the pop, and the engine of the player who took it applies their heal, shield, speed and jump, exactly once per event.
  • Every message counts once. Every kit message carries an id of its own, and a repeat is dropped, so a message that reaches an engine twice is handled once. After a live edit of the kit, the old copy's handlers stay registered (#19348), so they check that their copy is still the current one and stand down otherwise; an edit never leaves two copies answering.
  • The counts live in one place. Counters and letters live in the synced PickupLedger, and only its owner writes it. The host makes it. When the player who started play leaves, nobody counts as host any more (#19347), so then the lowest-numbered player in the play room makes it after Pickups.LEDGER_FALLBACK_S (2.5) seconds. As a safeguard, a moment after a new player appears in the play room, the ledger's owner makes it again with the same counts (Pickups.LEDGER_REPUBLISH_S, 1 second), so a late joiner always receives a fresh one. If two ledgers ever meet, every engine keeps the one with the lower sync id, and the other's counts are folded into it.
  • Shared or per-player. A shared pickup has one available flag. A perPlayer pickup keeps a synced taken map of who has had it, so each player has their own copy.
  • Settings are synced. prefab and the other settings are written by the pickup's owner and sync to every engine. From any other engine, setPrefab asks the owner to make the change.

Seen with two players. 2.2.0 and 2.2.1 were played with two engines in one play session, the host and a player who wasn't hosting:

  • Each kind of pickup was dropped at the other player's feet, and their own engine picked it up, sending the pickup and their player as entity references.
  • Coins, keys, a letter and XP were counted once under their name in the host's ledger.
  • Heals and shields reach the player who isn't hosting: a heart healed them 20 → 45, and a shield cell took their shield 0 → 30.
  • Speed and jump took their controller from 2.5 to 4 and from 5 to 7.75.
  • With damage, their hit on the host counted double. With invincible, 30 damage to them changed nothing.
  • With the magnet, a pickup out of reach flew to them.
  • One coin under both players was taken exactly once.
  • When the host left play, the other engine took over the pickups and kept deciding them.
  • prefab = "pixelGem" written by a coin's owner reached the other engine, and setPrefab called by the player who wasn't hosting changed a pickup the host owned. Old names worked the same way.
  • With the other engine hosting, a player joining late read everyone's counts as they were: the host's player had 2 coins, 1 key, 10 XP and the letter Z, exactly as before the join.
  • A coin taken from the host's gallery disappeared on the player's own engine, came back when the host respawned it, and played its pop and sound there.
  • On a per-player gem, the player took their own copy while the host's player kept theirs, and their copy came back on its own timer.
  • A blinking coin's expiry, decided by the host, reached the other engine.
  • Walking up to a chest the host owned opened it, and all 12 burst coins appeared on both engines.
  • The counter on the screen of the player who wasn't hosting showed their own counts from the host's ledger (7 coins, 3 gems, 1 key, 10 XP, Z), with both players listed.
  • In a web browser. The same check, with the person's browser hosting (platform = "browser") and an editor as the other player, passed 12 of 12 for the browser player: coins, keys, a letter and XP counted once under their name; a heart healed them 60 → 85; a shield cell took their shield 0 → 30; speed 2.5 → 4 and jump 5 → 7.75; their hit counted double with damage; invincible stopped 30 damage; the magnet pulled a pickup to them; one coin under both players was taken once. SecondWind and juiceKit both loaded in the browser from the copies that come with pickupsKit.

How it is tested. One engine can't be two real players (#18688, #19114), so the tests play both ends of the network through the same handlers the relay runs (_deliver). As the host: the other player's claims for every kind of pickup, naming the pickup and their avatar by entity, are each decided once, counted under their key, refused the second time, and announced with entity references. As the other player's engine: the host's announcements heal and shield their own player on the next frame, boost speed and jump on their CharacterController, double their damage, make them invincible and give them a magnet. The "two players" test runs 20 coins and a heart through two players whose claims arrive early, late and twice; every coin is taken once.

For testing your own game's netcode (internal, not a stable API): _deliver(channel, fromPeer, ...) runs one of the kit's network handlers (pk:claim, pk:got, pk:ledger, …) as if a message had arrived from fromPeer. _tap(fn) calls fn(channel, ...) for everything this engine broadcasts and returns an unsubscribe function.

Performance in the browser

The kit is built to keep a busy level smooth in a web browser:

  • No pickup shadows by default. Turning them off cut the gallery's sun shadow drawing from about 4.9 ms to 2.2 ms a frame and its frame spikes from 29 to 3. Use castShadows only where it matters.
  • Visuals are reused. A pickup that is removed or changes look parks its model, and the next pickup of that look takes it back instead of building a new one. Repeat bursts and look switches cost a fraction of a fresh build.
  • First builds are spread out. In play, pickups appearing for the first time build at most Pickups.BUILD_BUDGET_MS (3 ms) of models a frame, and always at least one. A wave of spawns therefore takes a few frames instead of stalling one. A prefab or letter change never waits.
  • Labels: show and hide, don't rewrite. Changing a Text3D label's text redraws it, about 5 ms each time. For text that cycles through known values, make one label per value and show the one you need. Showing or hiding a label costs about 0.01 ms. The gallery's look-switch label works this way.

Known limits

Engine problems that still affect the kit, each with its GitHub issue:

  • #19339: the editor's checker flags lookups inside the kits that come with pickupsKit. In a fresh install, the bundled copies of Lifeline, juiceKit and SecondWind show warnings such as asset reference "~.Health" could not be resolved. They are warnings only: the lookups resolve when the game runs, and nothing blocks publishing. pickupsKit's own lookups (SecondWind.Rules, Vitals, HUD, Trap) are no longer flagged.
  • #19340: a setting with a fixed list of choices can't take old names. The prefab list holds only the new names, so writing an old id such as cartoon_coin straight into prefab is refused. Old ids go through look, spawn, setPrefab, setLook and burst. The editor's list for look shows the old ids after the new names.
  • #18688, #19114, #14448 and #20946: one engine can't be two players. The loopback test mode doesn't echo messages (#18688), an agent working inside the engine has no way to bring in a second player (#19114) or start a web engine (#20946), and two engines signed in to the same account collide as one player (#14448). The kit's own tests therefore drive both ends of the network through _deliver, and a real two-player check needs a second engine or browser tab on a second account, as in "Seen with two players" above.
  • #22451: installing scoreKit after pickupsKit leaves extra copies, and the MatchFlow one logs errors. scoreKit uses the pickupsKit already in your world, as the example guide does, but the install also writes copies under /source/deps/.../versions/: a second MatchFlow package under deps/40bc9b7f-d32c-427f-b0ac-22d25071e2fa/versions/, and two lone Lifeline files, Lifeline.package/api.module and Lifeline.package/Health.component, under deps/45f92606-2e79-4b2b-8e03-b1fa2649e5c2/versions/. In a fresh world set up exactly that way, only the MatchFlow copy logged errors: none while editing, four the first time Play was pressed after the world was reopened, none on the second Play, and two more the first time the kit looked up a player's health. The two Lifeline files logged nothing. Lifeline kept using its own complete Health, SpawnPoint and Projectile parts, so pickupsKit had nothing to redirect, and hearts healed as usual: damage took the player to 80 and a heart brought them back to 100.
  • #20750: frame rate of the showcase gallery in a web browser. The gallery holds every look at once, with labels and lights, and its frame rate in a browser is an open engine issue. "Performance in the browser" below has what the kit itself does to keep pickups cheap.
  • #19258: the ZeroMind description can lag a release. For a while after a new version is published, its ZeroMind page can still show the previous description. The README and guides in your world after an install are the current ones.
  • #19347: nobody is host once the player who started play leaves. The host role stays with whoever started the play session, even after they leave, so code waiting for the host never runs. The kit works around it for its counts: when nobody is host, the lowest-numbered player in the play room makes the ledger. Your own host-only code (spawning enemies, starting a round) needs the same care.
  • #19348: a message handler can't be removed, and old ones keep running after a live edit. Each time the kit's code is edited while the game runs, the previous copy's handlers stay registered. The kit's old handlers check that they are still current and do nothing otherwise, so live edits are safe. A full reload of play clears them.

Showcase and tests

The world this package lives in, "Treasure Trove", opens on a gallery. It is set up exactly as a one-install world: pickupsKit in /source, and the kits it builds on only as its dependencies, at the versions a fresh install brings (SecondWind 1.3.1, juiceKit 1.2.8, Lifeline 1.0.1, MatchFlow 1.3.1; a fresh install can bring MatchFlow 1.0.0 instead). It has every look, labelled and grouped by style, and a station for each behaviour:

  • a respawning coin;
  • blink and vanish;
  • a coin burst from a chest;
  • a magnet line;
  • a shared pickup and a per-player one side by side;
  • hearts and shields beside a lava trap;
  • power-ups;
  • spelling a word;
  • a coin that cycles through prefabs, the pixel gem among them, by setting its prefab exactly as "Switching a look" above describes.

Every look's label shows its main prefab name, the one you type to use it.

pickupsKit.pickupskit is the test suite. It covers every public call of the api, logic, catalog, sounds, meshes, visual and fonts, the new names and every old id, prefab and look, the player who isn't hosting, and checks this README against the code: the version heading, the kit versions above, a row with style, kind, effect and size for every look, the quick start (short, compiles, real names) and this Known limits list. Run it with tools.use("tests", "run", { suite = "pickupskit" }).

Version

2.3.14, which matches package.yaml (pickupsKit.catalog.VERSION, checked by the tests).

  • 2.3.14: restore(target?) makes taken pickups available again for a new round: a one-time pickup someone took comes back at once for everyone, put back by the machine that owns it (other machines ask it over the network). A test covers it.
  • 2.3.13: the juiceKit line names the version an install brings (1.2.10; it said 1.2.8). Behaviour is unchanged.
  • 2.3.12: Every file that names SecondWind, juiceKit or Lifeline (the api, catalog and test modules) is recorded again against SecondWind 1.4.7, juiceKit 1.2.10, MatchFlow 1.4.0 and Lifeline 1.0.4, so an install no longer brings older single-file copies of SecondWind, MatchFlow or Lifeline beside the current ones; current engine library. No pickup behaviour changed.
  • 2.3.11: Dependencies brought current: SecondWind 1.4.7, juiceKit 1.2.10, MatchFlow 1.4.0 and Lifeline 1.0.4, the releases the other kits around pickupsKit use, so an install that brings pickupsKit beside them lands one release of each instead of two. The world also moved to the current engine library. No pickupsKit code changed; its suite runs 86 of 86.
  • 2.3.10: A pickup more than 60 m from every collector this machine moves updates one frame in ten (carrying the elapsed time along), so a long course full of coins costs little while you are far from them. Nothing changes within 60 m.
  • 2.3.9: Its tests find the package's own files wherever it is installed (at /source, or under /source/deps when another package installs it). In a world where platformer3dKit installed it, 6 of its tests failed because they read README.md, package.yaml and source files from a fixed /source/pickupsKit.package path.
  • 2.3.8: the kit requires its own modules relative to its package (~.api, ~.catalog, ~.meshes) instead of @root::pickupsKit.*, which only names a pickupsKit installed at a world's source root. A world that got pickupsKit as a dependency (under deps/, e.g. through inventoryKit or economyKit) failed with "module '@root::pickupsKit.meshes' not found".
  • 2.3.7: on today's engine entity.exists logs an error for a name passed to it, even inside pcall, and the kit asked it about player keys such as p10: in a race with item boxes that was hundreds of errors a second. The kit now asks it only about entity ids.
  • 2.3.6:
    • Package description rewritten: it now says plainly what pickupsKit gives a creator and how to install it (search ZeroMind for "pickupsKit", or install asset 0d70dd00-9297-45d5-a290-5a51b9f9e262; one install brings everything it builds on). No kit code, guide or other README text changed.
  • 2.3.5:
    • juiceKit's example guide is linked: both guides and this README now link "Make your game feel juicy step by step with hit feedback, explosions and damage numbers" beside juiceKit's how-to guide. It comes into your world with pickupsKit.
    • The scoreKit leftovers, as they behave (#22451): 2.3.4 said every leftover copy loads and fails, that this happens when the world opens, and that pickupsKit points Lifeline at its complete copy. A fresh-world test showed otherwise: only the MatchFlow copy logs errors (none while editing, four on the first Play after reopening the world, none on the second, two more the first time the kit looks up a player's health); the two lone Lifeline files log nothing; Lifeline keeps using its own complete parts by itself, and hearts heal as usual. The README and both guides now say exactly that. No kit code changed.
  • 2.3.4:
    • Easier to find: both guides now open by saying they cover collectible pickups that respawn, the way people search for them, and their search descriptions and tags say it too.
    • What installing scoreKit leaves behind, told as it is (#22451): the guides and Known limits named only an older MatchFlow copy and called it unused. The install also leaves two lone Lifeline files (api.module, Health.component), and the engine does load these copies and logs errors from them, at world open and during play. Pickups, scoring and health keep working.
    • Example guide: the coin ring is 12 m across (each coin 6 m out from the middle), as the code places it.
    • Builds on: a fresh install can bring MatchFlow 1.0.0 or 1.3.1; the release an install picks has varied. No kit code changed.
  • 2.3.3:
    • The showcase world runs the same dependencies a fresh install brings: SecondWind 1.3.1, juiceKit 1.2.8, Lifeline 1.0.1 and MatchFlow 1.3.1. So SecondWind's and juiceKit's guides, which the two pickupsKit guides link, open in Treasure Trove too. Played after a clean reload: 120 damage then a heart (30 → 55 through SecondWind 1.3.1), a coin, a jump orb, and juiceKit's pop on each grab. 86 of 86 tests, twice. No kit code changed.
  • 2.3.2:
    • README: the #19339 entry now says where the checker's false warnings still show (inside the kits that come with pickupsKit; pickupsKit's own SecondWind lookups are no longer flagged). Played the example guide word for word in a second brand-new world after 2.3.1 was published: same results, and every guide link opened. No kit code changed.
  • 2.3.1:
    • Two guides ship in the package: "How to add coins, gems and power-ups to my game" and "Make a coin and gem collecting game with power-ups and respawning pickups". See "Guides" above.
    • Checked on today's engine in a brand-new world that installed only pickupsKit: the quick start as written, hearts healing through SecondWind 1.3.1, power-ups, juiceKit 1.2.8, and 86 of 86 tests. No kit code changed.
    • README: your own scripts can now require SecondWind and juiceKit directly (#19199 is fixed), and Lifeline's lone old copies (#19260) no longer land in a fresh install, so both left Known limits. A brand-new world already has a build.luau for the quick start. Known limits add #14448, #20946, #22451, #20750 and #19258, and #19339 now names where the checker's false warnings still show (the bundled kits' own files, no longer pickupsKit's).
  • 2.3.0:
    • heart, speedOrb, damageOrb, jumpOrb, xpOrb and ammoCrate are main names (they were redHeart, speedCore, damageCore, jumpCore, xpShard and ammoBox, which still work, as do the pre-2.2 ids). looks() and look() list every other name a look answers to as otherNames; catalog.OTHER_NAMES holds them.
    • Gallery: each label shows the look's main name; the look switcher sets the coin's prefab, as the README says to; the gallery scene saves with nothing pending, so clearing and reloading it gives every pickup back.
  • 2.2.1:
    • Played with two players, start to finish. Every behaviour in "Seen with two players" was watched across two engines, with each engine taking a turn as host. That covers every pickup kind for the player who isn't hosting, per-player copies, late joiners, respawns, expiries, bursts and chests, the pop and sound, the counter, and prefab switches.
    • collect events carry prefab as well as look (the README's own example read ev.prefab, which was missing).
    • Who can write prefab: the README says it plainly. The pickup's owner writes the setting, and setPrefab works from any engine.
    • Known limits now name only problems that still exist, each with its GitHub issue.
    • Heals and shields reach a player in a web browser (played 12 of 12, see "Seen with two players"). Messages also carry each entity's sync id as a safeguard.
    • Hearts heal in a fresh install. Lifeline's own health part resolved to a lone old-version copy that doesn't compile (#19260), so HK.attach gave no health. pickupsKit now points Lifeline at the complete copy when it loads SecondWind. Lifeline is now a direct dependency of pickupsKit, at the same 1.0.1.
    • Every message counts once. A live edit of the kit left the old copy's handlers answering too (#19348). Messages now carry ids, repeats are dropped, old handlers stand down, and a heal or shield is applied exactly once per event.
    • The counts ledger always exists, for everyone. It was made only by the host, and nobody counts as host once the player who started play leaves (#19347), so a session could count nothing. The lowest-numbered player in the play room now makes it when nobody is host, its owner makes it again when a new player joins, and two ledgers fold into one.
    • peerReport() and selfReport() read every engine's view of the kit from yours.
    • Tests: 85, including entities that arrive as raw data, a heal heard twice, repeated messages, the ledger election, folding two ledgers and making the ledger again for a joining player.
    • Played in a web browser: every pickup kind, 12 of 12, for a browser player (see "Seen with two players").
  • 2.2.0:
    • Pickups work for every player, not just the host. The kit sent pickup and player ids as text, but every engine has its own ids for the same entity, so a claim from a player who wasn't hosting named nothing the host knew. Now pickups, chests and players cross the network as entity references. Coins, keys, letters, XP, hearts, shields and every power-up reach whoever touched them; a coin is still only ever taken once.
    • prefab is the setting, with a short name for every look (goldCoin, pixelGem, speedCore, healingPotion, brassKey...). look and every old id (cartoon_coin, real_gold_coin...) keep working. Added setPrefab, oldId on looks(), catalog.OLD_ID and catalog.PREFAB_IDS; the chest takes prefab too.
    • One install. Installing pickupsKit now brings SecondWind 1.2.0, juiceKit 1.2.2, Lifeline 1.0.1 and MatchFlow 1.0.0 with it, and the kit uses them. Added healthParts() for SecondWind's components; your own code reaches SecondWind through Pickups.health().
    • Tests: 77, including the new names, prefab and look, the player who isn't hosting, and walking up to a chest.
    • Chests open when you walk up to them anywhere. Since 1.1.0 the walk-up check measured from the middle of the map, so a chest away from it only opened from code.
    • Showcase: set up as a one-install world, every pickup by its new name.
  • 2.1.0: pickups load without waiting for SecondWind or juiceKit; SecondWind 1.2.0; heals and shields heard in a message apply on the next frame.
  • 2.0.0: renamed to pickupsKit (from pickupKit, same guid); pixelGem; five new looks; size tags; dependency versions; remote pops on the next frame.
  • 1.1.1: works with SecondWind 1.1.1; passing a Pickup component no longer logs.
  • 1.1.0: performance in the browser: pickup shadows off by default, pooled visuals, a per-frame build budget.
  • 1.0.1: a two-player test of 20 coins and a heart.
  • 1.0.0: first release, as pickupKit.