Skip to content

KubeJS Guide

hp-1e edited this page Nov 20, 2026 · 1 revision

Language: English | 简体中文

KubeJS Integration Guide

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.


1. Script Placement & Instant Hot-Reload

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:, or archogenum:).
  • Instant Hot-Reload: Run /genereload (alias /genecore reload, requires OP level 2) in-game. It reloads server_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.

2. Registering Traits, Genes & Genomes

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']
    )
})

GeneBuilderJS Methods Reference

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)

3. Gene Tag System

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).
  • 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>

4. Runtime Events (kubejs/server_scripts/)

Combat Events (geneAttack / geneHurt)

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)).

Periodic Tick Event (geneTick)

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.

Live Extraction Event (liveExtract, cancellable)

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.

Xenofruit Synthesis Event (synthesize, cancellable)

ArchogenumEvents.synthesize(event => {
    // event.player, event.genes, event.complexity, event.hasArchogene(), event.resultStack
    // event.cancel() // blocks synthesis
})

Xenotype Changed Event (xenotypeChanged)

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')
})

5. Global Helper API (ArchogenumJS / ArchogenumAPI)

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