Repository navigation
KubeJS Guide
Language: English | 简体中文
Archogenum Addition includes native KubeJS integration (ArchogenumEvents, ArchogenumJS / ArchogenumAPI), allowing modpack authors to define Traits, Genes, Genomes, Gene Tags, and runtime gameplay logic directly in JavaScript.
ArchogenumEvents.registry works in both kubejs/startup_scripts/ and kubejs/server_scripts/.
-
Recommended: Put your gene registration scripts in
kubejs/server_scripts/(recommended namespaces:kubejs:,archogenum_addition:, orarchogenum:). -
Instant Hot-Reload: Run
/genereload(alias/genecore reload, requires OP level 2) in-game. It reloadsserver_scripts, hot-patches the running server & client Archogenum registries (trait→gene→genome), updates online players' active attribute modifiers, syncs Gene Tags, and updates client translations without running vanilla/reload.-
Note: Adding or replacing PNG textures still requires
F3 + T. Refreshing JEI recipe lists requires reloading JEI or rejoining the world.
-
Note: Adding or replacing PNG textures still requires
Use ArchogenumEvents.registry(event => { ... }) in kubejs/server_scripts/custom_genes.js:
ArchogenumEvents.registry(event => {
// 1) Attribute Modifier Trait
// Operations: 'addition', 'multiply_base', 'multiply_total'
event.createModifierTrait('kubejs:modifiers/dwarf_mining')
.add('minecraft:generic.armor', 'addition', 2.0)
.add('minecraft:generic.attack_speed', 'multiply_base', 0.15)
// 2) Custom Scripted Trait (displays in UI; logic handled via events below)
event.createCustomTrait('kubejs:ember_resonance', 'beneficial', 'Ember Resonance')
// 3) Raw Archogenum Trait JSON (for any native Archogenum trait type)
// event.createTraitJson('kubejs:custom_effect', { type: 'archogenum:effects', ... }, 'Custom Effect')
// 4) Register a Gene
event.createGene('kubejs:dwarf_vigor')
.beneficial() // .beneficial() | .harmful() | .cosmetic()
.offense() // .offense() | .defense() | .utility() (optional role)
.complexity(1) // complexity cost
.metabolicEfficiency(-1) // negative increases hunger, positive offsets it
.maxExpression(3) // 1..5
.color('#ff6b2b') // hex color
.texture('kubejs:textures/gui/gene/dwarf_vigor.png')
.cost('minecraft:iron_ingot', 8)
.cost('minecraft:blaze_powder', 4)
.trait('kubejs:modifiers/dwarf_mining')
.trait('kubejs:ember_resonance')
.tag('pyro') // or .tags(['pyro', 'core'])
.displayName('Dwarf Vigor')
.description('Sturdy subterranean constitution that boosts combat resilience.')
// 5) Bind Genes to Entity Genomes (mob extraction pools)
event.addGenome(
'kubejs:nether_warriors',
['minecraft:blaze', 'minecraft:magma_cube'],
['kubejs:dwarf_vigor']
)
})| Method | Description |
|---|---|
.beneficial() / .harmful() / .cosmetic() / .category(str)
|
Sets gene category |
.offense() / .defense() / .utility() / .role(str) / .group(str)
|
Sets gene role (used when split complexity or Curios plasmid slot is enabled; .utility() defaults complexity to 1 if unset) |
.complexity(int) |
Complexity points (>= 0) |
.metabolicEfficiency(int) |
Metabolic efficiency (positive or negative) |
.maxExpression(int) |
Max expression level (1 to 5) |
.archogene(boolean) |
Marks gene as an Archogene (requires Enchanted Golden Apple base) |
.color(hex) |
Hex color string (e.g. '#55ddff') |
.texture(rl) |
Gene icon texture path (16x16 PNG) |
.cost(itemId, count) |
Adds a synthesis catalyst item |
.trait(traitId) |
Attaches a trait ID |
.tag(tag) / .tags(list)
|
Attaches one or more Gene Tags |
.displayName(str) / .description(str)
|
Dynamic fallback name & description (overridable via lang/*.json) |
Gene Tags let you group genes by build/archetype (e.g. pyro, frost, void) and query how many active genes of a tag an entity has.
ArchogenumEvents.registry(event => {
// Define display name & custom hex color for a tag (optional)
// Localization key `gene_tag.archogenum_addition.<tag>` takes precedence if present in lang files
event.defineGeneTag('pyro', 'Pyro', '#ff6b2b')
// Tag an existing / vanilla Archogenum gene
event.tagGene('archogenum:pyrophobic_veins', 'pyro')
// Multiple tags at once:
// event.tagGene('archogenum:lava_stride', ['pyro', 'mobility'])
})-
Tooltip Display:
- When split complexity & Curios plasmid slot are off (default): shows
[Pyro] Pyrophobic Veins I(no bracket if untagged). - When split complexity or Curios plasmid slot is on: shows
[Defense/Pyro] Pyrophobic Veins I(or[Defense]if untagged).
- When split complexity & Curios plasmid slot are off (default): shows
- Counting Active Tagged Genes (includes both main Xenotype and equipped Curios Exo-Plasmids, without double-counting):
let count = ArchogenumJS.countGenesWithTag(player, 'pyro')
let hasAny = ArchogenumJS.hasGeneTag(player, 'pyro')
let exprSum = ArchogenumJS.getTagExpressionSum(player, 'pyro')
let list = ArchogenumJS.getGenesWithTag(player, 'pyro') // List<GeneInstanceWrapper>Filtered by target Gene ID:
// Triggered when an entity with 'kubejs:dwarf_vigor' deals damage
ArchogenumEvents.geneAttack('kubejs:dwarf_vigor', event => {
let attacker = event.entity
let target = event.target
let pyroCount = ArchogenumJS.countGenesWithTag(attacker, 'pyro')
// Example: +5% damage per Pyro gene, scaled by expression level
event.damage = event.damage * (1.0 + pyroCount * 0.05 * event.scale)
})
// Triggered when an entity with 'kubejs:dwarf_vigor' takes damage
ArchogenumEvents.geneHurt('kubejs:dwarf_vigor', event => {
if (event.source.is('inFire') || event.source.is('onFire')) {
event.damage = event.damage * 0.8
}
})Event properties: event.entity, event.attacker, event.target, event.source, event.geneId, event.expression, event.scale, event.damage (getDamage() / setDamage(float)).
ArchogenumEvents.geneTick('kubejs:dwarf_vigor', event => {
let player = event.player
if (player && event.level.time % 40 === 0) {
// Runs every 2 seconds for players carrying this gene
}
})Event properties: event.level, event.entity, event.player, event.geneId, event.expression, event.scale.
ArchogenumEvents.liveExtract(event => {
// Inspect extracted genes or modify the resulting Echo Vessel
let genes = event.extractedGenes
// event.vesselStack = ...
// event.cancel() // cancels giving the vessel
})Event properties: event.player, event.target, event.extractor, event.resonant, event.vesselStack, event.extractedGenes.
ArchogenumEvents.synthesize(event => {
// event.player, event.genes, event.complexity, event.hasArchogene(), event.resultStack
// event.cancel() // blocks synthesis
})ArchogenumEvents.xenotypeChanged(event => {
// event.entity, event.player, event.genes, event.empty, event.complexity,
// event.metabolicEfficiency, event.hasGene('kubejs:dwarf_vigor'), event.getExpression('kubejs:dwarf_vigor')
})Both ArchogenumJS and ArchogenumAPI are bound globally in KubeJS scripts:
| Method | Return | Description |
|---|---|---|
ArchogenumJS.hasGene(entity, geneId) |
boolean |
Whether entity has the gene active |
ArchogenumJS.getGeneExpression(entity, geneId) |
int |
Active expression level (0 if absent) |
ArchogenumJS.getGenes(entity) |
List<GeneInstanceWrapper> |
All active genes (id, expression, maxExpression, complexity, metabolicEfficiency, category, role, archogene, scale, tags, hasTag(tag)) |
ArchogenumJS.countGenesWithTag(entity, tag) |
int |
Count of active genes with given tag |
ArchogenumJS.hasGeneTag(entity, tag) |
boolean |
Whether entity has any active gene with given tag |
ArchogenumJS.getGenesWithTag(entity, tag) |
List<GeneInstanceWrapper> |
Active genes matching tag |
ArchogenumJS.getTagExpressionSum(entity, tag) |
int |
Sum of expression levels of active genes with tag |
ArchogenumJS.getGeneTags(geneId) |
List<String> |
All tags registered on a gene ID |
ArchogenumJS.getTotalComplexity(entity) |
int |
Total complexity of entity's xenotype |
ArchogenumJS.getRoleComplexity(entity, role) |
int |
Complexity for 'offense' or 'defense'
|
ArchogenumJS.getMaxRoleComplexity(role) |
int |
Configured max complexity for role |
ArchogenumJS.getTotalMetabolicEfficiency(entity) |
int |
Total metabolic efficiency |
ArchogenumJS.addGene(entity, geneId[, expr]) |
boolean |
Adds/updates gene on server-side entity |
ArchogenumJS.removeGene(entity, geneId) |
boolean |
Removes gene from server-side entity |
ArchogenumJS.setGenes(entity, geneMap) |
void |
Replaces xenotype from { 'id': expr } map |
ArchogenumJS.clearXenotype(entity) |
void |
Clears all genes from entity |
ArchogenumJS.discoverGene(player, geneId) / forgetGene / hasDiscoveredGene / discoverAllGenes
|
boolean / int
|
Manage player gene codex discoveries |
ArchogenumJS.createSingleVessel(geneId, expr) |
ItemStack |
Creates an Echo Vessel with one gene |
ArchogenumJS.createEchoVessel(geneMap) |
ItemStack |
Creates an Echo Vessel from { 'id': expr }
|
ArchogenumJS.createXenofruit(geneMap) |
ItemStack |
Creates a Xenofruit from { 'id': expr }
|
ArchogenumJS.getStoredGenes(stack) |
Map<String, Integer> |
Reads stored gene map from a Vessel/Xenofruit |