Research and discoveries in your game (research.samples) #

What it is for #

research.samples turns items the player brings back into discoveries. A sample is an item of inventory.items; studying one at a lab takes a moment, uses the item up and yields one finding drawn among those the sample can give. A finding is a document: a name, a rarity label and the actions it runs when found (unlock a recipe, a structure, a species, give an item, set a variable, emit an event). The kit knows nothing of what is studied or learned: that belongs to the other kits of the game. A codex keeps what was found and shows the rest as unknown. It suits exploration, archaeology, science, cooking, alien technology and detective games.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "research.samples" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "research.samples",
                              config: { "needsLab": true, "labReach": 5 } }

It requires inventory.items and game.engine, so installing it brings them. Targets: web and the Rust kit host (native player and the engine wrappers).

First example #

<!-- test: kits/game_engine/host/tests/research_samples.rs::a_study_needs_a_lab_and_the_item_then_yields_each_finding_once --> Two collections in the game data, and an inventory.items item shard:

"samples":  [ { "id": "shard", "name": "Shard", "item": "shard", "seconds": 0.5, "findings": ["map", "rune"] } ],
"findings": [ { "id": "map", "name": "Map", "weight": 3 }, { "id": "rune", "name": "Rune" } ]

With the default needsLab, study("shard") is refused with reason lab until a lab is open (placeLab then open), then with item while the bag has no shard. With a shard held it answers { ok: true }; a second call answers busy. After 0.5 s research.found fires with one finding. Both findings are found once, so the third study ends with research.nothing, taking its shard.

Settings and defaults #

Input: research_menu (key J) opens or closes the research screen. Without a lab it shows the codex alone, unless needsLab is off.

Data: samples and findings #

A sample (collection samples) has id, name, item (required: one is used up per study), findings (required: ids it can yield; a finding may be listed by several samples), seconds (study length, default 5; 0 is at once), description and fallback (actions run when nothing is left to find).

A finding (collection findings) has id, name (required), description, rarity (a free display label such as common, rare, unique), weight (share of the draw among the findings left, default 1; 0 is never drawn, only granted), once (found a single time, default true; false lets it come again, e.g. a material) and actions run when found.

The draw depends only on the game seed and the number of draws made, so the same game gives the same findings and a loaded game continues as the saved one would have. A finding found in one sample leaves the draws of every sample that lists it.

Lab, service and verbs #

A lab is any entity carrying research.lab ({ label? }): an editor instance with the research_lab component, a placed structure whose components carry research.lab, or placeLab from a script. With interaction.use it offers the labLabel prompt and using it opens the research screen.

Service research.samples:

• samples(): the samples with held, found, total and exhausted.
• findings(): the findings with found (times found).
• study(id): { ok, reason? }; reasons unknown, lab, busy, item.
• job(): { sample, left, total, ratio } or null.
• found(finding): times found. grant(finding): counts a finding and runs its actions, no study.
• open(lab?), close(), current(), placeLab(at, yaw?, label?).

Trigger actions: grant_finding { finding }, study_sample { sample } (one draw at once, as a reward: no lab, no time, no item used). Conditions: finding_found { finding, count? }, sample_exhausted { sample }.

Events and variables #

It listens to interaction.requested, entity.spawned and game.phase (the screen closes when the game pauses). The saved state is the count of each finding, the running study and the number of draws.

Hooks and modding #

{ "id": "quick_ore", "hook": "research.study", "match": { "sample": "ore" }, "mul": { "seconds": 0.5 } }

A mod may override needsLab, labReach and labLabel, and add, patch or remove entries of samples and findings.

When it does not do what you expect #

• research.failed with lab: no lab is open and needsLab is on; open one or turn needsLab off.
• research.failed with item: the bag holds none of the sample item.
• A finding never comes again: once defaults to true; set "once": false.
• A finding never appears: its weight is 0 (granted only), or no sample lists it.

Limits #

• One study at a time.
• The kit does not define what a finding does: its actions call the other kits.
• No built-in lab model: provide a research_lab asset.

Versions #

Kit 1.1.1; service research.samples 1.0.0. Hooks and moddable data since 1.1.0 (game.engine 1.2).