DBot/KStarbound
DBot/KStarbound
3
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
9687c25bb0
KStarbound/ADDITIONS.md

25 KiB
Raw Blame History

Modding and behavior changes

This document briefly documents what have been added (or removed) regarding modding capabilities or engine behavior(s)

This document is non-exhaustive, engine contains way more behavior change bits than documented here, but listing all of them will be a hassle, and will pollute this document.

Prototypes

  • treasurechests now can specify treasurePool as array
  • damageTable can be defined directly, without referencing other JSON file (experimental feature)
  • environmentStatusEffects of visitable world parameters now accept StatModifiers and not just unique status effects as Strings
    • Keep in mind, putting stat modifiers there will blow up original clients due to Json deserializer expecting only strings (despite StatusController treating environmentStatusEffects as field containing either StatModifier or String)

Biomes

  • Tree biome placeables now have variantsRange (defaults to [1, 1]) and subVariantsRange (defaults to [2, 2])
    • variantsRange is responsible for "stem-foliage" combinations
    • subVariantsRange is responsible for "stem-foliage" hue shift combinations
      • Rolled per each "stem-foliage" combination
      • Also two more properties were added: sameStemHueShift (defaults to true) and sameFoliageHueShift (defaults to false), which fixate hue shifts within same "stem-foliage" combination
    • Original engine always generates two tree types when processing placeable items, new engine however, allows to generate any number of trees.

Dungeons

  • front and back brushes now can properly accept detailed data as json object on second position (e.g. ["front", { "material": ... }]), with following structure (previously, due to oversight in code, it was impossible to specify this structure through any means, because brush definition itself can't be an object):
val material: Registry.Ref<TileDefinition> = BuiltinMetaMaterials.EMPTY.ref
val modifier: Registry.Ref<TileModifierDefinition> = BuiltinMetaMaterials.EMPTY_MOD.ref
val hueShift: Float = 0f
val modHueShift: Float = 0f
val color: TileColor = TileColor.DEFAULT
  • item brush now can accept proper item descriptors (in json object tag),
    • Previous behavior remains unchanged (if specified as string, creates randomized item, if as object, creates exactly what have been specified)
  • liquid brush now can accept 'level' as second argument
    • Previous behavior is unchanged, ["liquid", "water", true] will result into infinite water as before, but ["liquid", "water", 0.5, false] will spawn half-filled water
    • In tiled, you already can do this using "quantity" property
  • dungeonid brush has been hooked up to legacy dungeons and now can be directly specified inside "brush" (previously they were only accessible when using Tiled' tilesets).
    • By default, they mark entire part of dungeon with their ID. To mark specific tile inside dungeon with its own Dungeon ID, supply true as third value to brush (e.g ["dungeonid", 40000, true"])
    • Tiled map behavior is unchanged, and marks their position only.

.terrain

Please keep in mind that if you use new format or new terrain selectors original clients will explode upon joining worlds where new terrain selectors are utilized.

  • All composing terrain selectors (such as min, displacement, rotate, etc) now can reference other terrain selectors by name (the .terrain files) instead of embedding entire config inside them
    • They can be referenced by either specifying corresponding field as string, or as object like so: {"name": "namedselector"}
    • min, max and minmax terrain selectors now also accept next format: {"name": "namedselector", "seedBias": 4}
  • mix terrain selector got mixSeedBias, aSeedBias and bSeedBias fields, whose deviate respective selectors seeds (default to 0)
  • displacement terrain selector has seedBias added, which deviate seed of source selector (default to 0)
  • displacement terrain selector has xClamp added, works like yClamp
  • rotate terrain selector has rotationWidth (defaults to 0.5) and rotationHeight (defaults to 0.0) added, which are multiplied by world's size and world's height respectively to determine rotation point center
  • Added min terrain selector, opposite of existing max (json format is the same as max)
  • Removed cache terrain selector due it not being documented, and having little practical value
  • perlin terrain selector now accepts type, frequency and amplitude values (naming inconsistency fix)
  • ridgeblocks terrain selector now accepts amplitude and frequency values (naming inconsistency fix);
  • ridgeblocks has octaves added (defaults to 2), perlinOctaves (defaults to 1)

player.config

  • Inventory bags are no longer limited to 255 slots
    • However, when joining original servers with mod which increase bag size past 255 slots will result in undefined behavior (joining servers with inventory size bag mods will already result in nearly instant desync though, so you may not ever live to see the side effects; and if original server installs said mod, original clients and original server will experience severe desyncs/undefined behavior too)

.item

  • inventoryIcon additions if specified as array:
    • scale, either as float or as vector (for x and y scales); both in prototype file and in parameters.
    • color (defaults to white [255, 255, 255, 255])
    • rotation (in degrees, defaults to 0)
    • mirrored (defaults to false, this is different from setting scale to -1f since it obeys center point)
    • centered (defaults to true)
    • fullbright (defaults to false)

.liquid

  • liquidId is no longer essential and can be skipped; engine will not assign it to anything, but liquid will still be fully functional from engine's point of view
    • However, this has serious implications:
      • Liquid will become "invisible" to legacy clients (this is not guaranteed, and if it ever "bleeds" into structures sent to legacy clients due to missed workarounds in code, legacy client will blow up.)
      • Lua scripts written solely for original engine won't see this liquid too (this includes base game assets!), unless they use new improved functions
  • liquidId can be specified as any number in 1 -> 2^31 - 1 range (0 is reserved for "empty" meta-liquid)
    • This will make liquid "invisible" to original clients only, Lua code should continue to function normally
      • This is not guaranteed, and if it ever "bleeds" into structures sent to legacy clients due to missed workarounds in code, legacy client will blow up.

.matierial

  • Meta-materials are no longer treated uniquely, and are defined as "real" materials, just like every other material, but still preserve unique interactions.
  • materialId is no longer essential and can be skipped, with same notes as described in liquidId.
  • materialId can be specified as any number in 1 -> 2^31 - 1 (softly excluding reserved "meta materials" ID range, since this range is not actually reserved, but is expected to be used solely by meta materials), with legacy client implications only.
  • Implemented isConnectable, which was planned by original developers, but scrapped in process (defaults to true, by default only next meta-materials have it set to false: empty, null and boundary)
    • Used by object and plant anchoring code to determine valid placement
    • Used by world tile rendering code (render piece rule Connects)
    • And finally, used by canPlaceMaterial to determine whenever player can place blocks next to it (at least one such tile should be present for player to be able to place blocks next to it)

.object

  • breakDropOptions and smashDropOptions items created now obey world's threat level
  • smashDropPool, breakDropPool, breakDropOptions and smashDropOptions are now deterministic (see worldgen section)

.matmod

  • modId is no longer essential and can be skipped, or specified as any number in 1 -> 2^31 range, with notes of materialId and liquidId apply.

Monster Definitions

New parameters merge rules

In addition to add, multiply, merge and override new merge methods are accepted:

  • sub (a - b)
  • divide (a / b)
  • inverse (b / a)
  • min
  • max
  • pow (a in power of b)
  • invpow (b in power of a)

Scripting

  • In DamageSource, sourceEntityId combination with rayCheck has been fixed, and check for tile collision between victim and inflictor (this entity), not between victim and attacker (sourceEntityId)
  • Contexts, where previously only entity bindings were available, now have entity-specific bindings exposed
    • Example: Status controller scripts now get monster bindings when running in context of Monster's status controller, etc
  • behavior.behavior third argument (specified commonly as _ENV) is ignored and can be omitted (set to nil)
    • It was used solely to get Lua engine (Lua execution context), and could have been deprecated long time ago even in original engine, because there is now a way in original engine to get Lua engine when binding is called
  • Added sb.logFatal, similar to other log functions
  • print(...) now prints to both console (stdout) and logs
  • sb.log functions now accept everything string.format accepts, and not only %s and %%
  • Added noise:seed(): long (object returned by sb.makePerlinSource)
  • Added noise:parameters(): Json (object returned by sb.makePerlinSource)
  • Added noise:init(seed: long), re-initializes noise generator with new seed, but same parameters (object returned by sb.makePerlinSource)
  • Added math.clamp(value, min, max)
  • Added math.lerp(t, a, b)

Random

  • Added random:randn(deviation: double, mean: double): double, returns normally distributed double, where deviation stands for Standard deviation, and mean specifies middle point
  • Removed random:addEntropy

animator

  • Added animator.targetRotationAngle(rotationGroup: string): double
  • Added animator.hasRotationGroup(rotationGroup: string): boolean
  • Added animator.rotationGroups(): List<string> (returns valid names for rotateGroup, currentRotationAngle and targetRotationAngle)
  • Added animator.transformationGroups(): List<string>
  • Added animator.particleEmitters(): List<string>
  • Added animator.hasParticleEmitter(emitter: string): boolean
  • Added animator.lights(): List<string>
  • Added animator.hasLight(light: string): boolean
  • Added animator.sounds(): List<string>
  • Added animator.effects(): List<string>
  • Added animator.hasEffect(effect: string): boolean
  • Added animator.parts(): List<string>

mcontroller

  • Added mcontroller.collisionPolies(): List<Poly>, since engine technically supports multiple convex bodies attached to one movement controller
  • Added mcontroller.collisionBodies(): List<Poly>, since engine technically supports multiple convex bodies attached to one movement controller
  • Added mcontroller.liquidName(): String?, returns nil if not touching any liquid
    • This addition marks mcontroller.liquidId(): Int deprecated

monster

  • Added monster.seedNumber(): Long, use this instead of monster.seed(): String
  • monster.level(): Double? returns nil if no monster level was specified
  • monster.setDamageParts(parts: Table?) now accepts nil as equivalent of empty table (consistency fix)
  • monster.setPhysicsForces(forces: Table?) now accepts nil as equivalent of empty table (consistency fix)
  • mosnter.setName(name: String?) now accepts nil to reset custom name

npc

  • npc.setDropPools(dropPools: Table?) now accepts nil
  • Added npc.beginSecondaryFire() which is alias for npc.beginAltFire()
  • Added npc.endSecondaryFire() which is alias for npc.endAltFire()

status

  • Implemented status.appliesEnvironmentStatusEffects(): Boolean, which exists in original engine's code but was never hooked up to Lua bindings
  • Implemented status.appliesWeatherStatusEffects(): Boolean, which exists in original engine's code but was never hooked up to Lua bindings
  • Implemented status.setAppliesEnvironmentStatusEffects(should: Boolean), which exists in original engine's code but was never hooked up to Lua bindings
  • Implemented status.setAppliesWeatherStatusEffects(should: Boolean), which exists in original engine's code but was never hooked up to Lua bindings
  • Added status.minimumLiquidStatusEffectPercentage(): Double
  • Added status.setMinimumLiquidStatusEffectPercentage(value: Double)

world

Additions

  • Added world.liquidNamesAlongLine(start: Vector2d, end: Vector2d): List<LiquidState>, will return Liquid' name instead of its ID
  • Added world.liquidNameAt(at: Vector2i): LiquidState?, will return Liquid' name instead of its ID
  • Added world.biomeBlockNamesAt(at: Vector2i): List<String>?, will return Block names instead of their IDs
  • Added world.destroyNamedLiquid(at: Vector2i): LiquidState?, will return Liquid' name instead of its ID
  • Added world.gravityVector(at: Vector2d): Vector2d. Attention: directional gravity is WIP.
  • Added world.itemDropLineQuery(p0: Vector2d, p1: Vector2d, options: Table?): List<EntityID>
  • Added world.playerLineQuery(p0: Vector2d, p1: Vector2d, options: Table?): List<EntityID>
  • Added world.objectLineQuery(p0: Vector2d, p1: Vector2d, options: Table?): List<EntityID>
  • Added world.loungeableLineQuery(p0: Vector2d, p1: Vector2d, options: Table?): List<EntityID>
  • Added world.loadUniqueEntityAsync(id: String): RpcPromise<EntityID>
  • Added world.findUniqueEntityAsync(id: String): RpcPromise<Vector2d?>
    • world.findUniqueEntity is legacy function, and to retain legacy behavior it will block world thread upon result() call if entity has not been found yet
    • world.findUniqueEntity won't block world thread if called on client worlds, though, and will behave equal to world.findUniqueEntityAsync
  • Added world.unsetUniverseFlag(flag: String): Boolean
  • Added world.placeDungeonAsync(name: String, position: Vector2d, dungeonID: Int?, seed: Long?): RpcPromise<Boolean>
  • Added world.tryPlaceDungeonAsync(name: String, position: Vector2d, dungeonID: Int?, seed: Long?): RpcPromise<Boolean>
  • Added world.materialColorName(pos: Vector2i, layer: String): String. Returns one of next strings:
    • "default"
    • "red"
    • "blue"
    • "green"
    • "yellow"
    • "brown"
    • "purple"
    • "black"
    • "white"
  • Added world.spawnLiquidPromise(pos: Vector2i, liquid: Any, quantity: Float): RpcPromise<Boolean>
    • However, correct clientside result will be returned only when using native protocol
  • Added world.damageTilesPromise(positions: List<Vector2i>, layer: String, damageSource: Vector2d, damageType: String, damageAmount: Double, harvestLevel: Int = 999, sourceEntity: EntityID = 0): RpcPromise<String>, which return one of next values on promise completion:
    • "none"
    • "protected"
    • "normal"
    • Keep in mind that it returns top-most damage status, which means:
      • If some tiles were protected, and others were not, it will return "normal".
      • If all tiles were protected, it will return "protected".
      • If none tiles were damaged, it will return "none".
  • Added world.damageTileAreaPromise(radius: Double, position: Vector2i, layer: String, damageSource: Vector2d, damageType: String, damageAmount: Double, harvestLevel: Int = 999, sourceEntity: EntityID = 0): RpcPromise<String>, with same notes as world.damageTilesPromise() apply
  • Added world.placeMaterialPromise(pos: Vector2i, layer: String, material: String, hueShift: Number?, allowOverlap: Boolean): RpcPromise<Vector2i>, returning promise of unapplied tile modifications
    • However, correct clientside result will be returned only when using native protocol
  • Added world.placeModPromise(pos: Vector2i, layer: String, modifier: String, hueShift: Number?, allowOverlap: Boolean): RpcPromise<Vector2i>, returning promise of unapplied tile modifications
    • However, correct clientside result will be returned only when using native protocol

Changes

  • world.entityHandItem(id: EntityID, hand: String): String now accepts "secondary" as hand argument (in addition to "primary"/"alt")
  • world.containerConsume(id: EntityID, item: ItemDescriptor, exact: Boolean?): Boolean? now accepts exact which forces exact match on item descriptor (default false)
  • world.flyingType(): String has been made shared (previously was server world only)
  • world.warpPhase(): String has been made shared (previously was server world only)
  • world.skyTime(): Double has been made shared (previously was server world only)
  • world.loadRegion(region: AABB): RpcPromise<nil> now returns promise for region load
    • Due to how engine handles world loading and unloading (it is completely async), mods which expect loadRegion to instantaneously load required regions will break. This will not be changed, mods must be adapted to new behavior
  • world.breakObject(id: EntityID, smash: Boolean = false): Boolean argument smash is now optional
  • world.placeDungeon(name: String, position: Vector2d, dungeonID: Int?, seed: Long?): Boolean now accepts optional seed. If not specified, engine will determine one (like original engine does).
    • Please update code to use world.placeDungeonAsync(), because there are absolutely no guarantees dungeon will be generated the moment world.placeDungeon() call returns
  • world.tryPlaceDungeon(name: String, position: Vector2d, dungeonID: Int?, seed: Long?): Boolean now accepts optional seed. If not specified, engine will determine one (like original engine does).
    • Please update code to use world.tryPlaceDungeonAsync, because there are absolutely no guarantees dungeon will be generated the moment world.tryPlaceDungeon call returns
  • world.setDungeonGravity(id: Int, gravity: Either<Double, Vector2d>) now accept directional vector. Attention: Directional gravity is WIP.
  • world.setMaterialColor(pos: Vector2i, layer: String, color: Any): Boolean
    • Now returns boolean whenever cell was set (returns false when called with position outside of loaded chunks)
    • Now accepts string name along integer index
  • world.spawnLiquid(pos: Vector2i, liquid: Any, quantity: Float): Boolean now accepts both liquid ID and liquid name. However, you should be using world.spawnLiquidPromise(pos: Vector2i, liquid: Any, quantity: Float): RpcPromise<Boolean> instead

Fixes

  • world.entityCanDamage(source: EntityID, target: EntityID): Boolean now properly accounts for case when source == target
  • world.containerStackItems(id: EntityID, items: ItemDescriptor): ItemDescriptor now actually does what it says on tin, instead of being equal to world.containerAddItems
    • ONLY for local entities, or when using native protocol (but why would you ever mutate containers over network in first place)
    • Remote entities on legacy protocol will behave like world.containerAddItems has been called
  • world.containerItemApply(id: EntityID, items: ItemDescriptor, slot: Int): ItemDescriptor is no longer equal to world.containerSwapItemsNoCombine and does what its docs say, but im not sure if it is ever makes sense
    • Clarification - Original docs are not very clear, but what it does is it tries to put provided item into target slot only if it contains item of same type (contains stackable). If slot is empty or item in slot can not be stacked with provided item, this function does nothing (and returns stack initially passed to the function)
    • ONLY for local entities, or when using native protocol (but why would you ever mutate containers over network in first place)
    • Remote entities on legacy protocol will try to simulate new behavior locally using item checks and remote putItems message

Deprecations

  • world.loadUniqueEntity() is busted in new engine and will cause major issues if used (because engine is incapable for synchronous loading of world chunks, everything is async)
    • If your mod is using it PLEASE switch to world.loadUniqueEntityAsync(id: String): RpcPromise<EntityID>
  • world.spawnLiquid() is deprecated, use world.spawnLiquidPromise() instead
  • world.damageTiles() is deprecated, use world.damageTilesPromise() instead
  • world.damageTileArea() is deprecated, use world.damageTileAreaPromise() instead
  • world.placeMaterial() is deprecated, use world.placeMaterialPromise() instead
  • world.placeMod() is deprecated, use world.placeModPromise() instead
  • world.placeDungeon() is deprecated, use world.placeDungeonAsync() instead
  • world.tryPlaceDungeon() is deprecated, use world.tryPlaceDungeonAsync() instead

Deterministic world generation

In new engine, entirety of world generation is made deterministic. What this means that given one world seed, engine will generate exactly the same (on best effort*) world each time it is requested to generate one (given prototype definitions which influence world generation are the same between generations).

To put it simply, when you visit a planet on your friend's server, it is expected* that in your singleplayer or on other server, given same set of mods installed (and both players are using new engine server or new engine client), you will get exactly the same planet as you saw before.

This includes, but not limited to:

  • Containers (such as chests)
  • Smashable objects (e.g. capsules, rocks)
  • random dungeon brush
  • Tree types / placement
  • Grass / bush variants and placement
  • Dungeon placement
  • Initial player spawn position in world
  • Microdungeon placement

However, this also means that instance worlds will generate 1:1 each time they are requested if there is seed specified for such world /instance_worlds.config. And since vanilla dungeons have it specified (and mod makers don't question "why" it is there), all mission dungeons will be generated 1:1 each time.

If you are mod creator, PLEASE update your mod(s), and remove seed from your dungeon worlds! Both new and old engines will provide random seed for you if you don't specify one inside /instance_worlds.config.

*On best effort - due to how worldgen code flow is structured, engine may rearrange generation events, which can yield slightly different results from execution to execution, such as one microdungeon taking precedence over another microdungeon if they happen to generate in proximity on chunk border (one dungeon generated in chunk A, second generated in chunk B, and they happened to overlap each other), and which one gets placed is determined by who finishes generating first; as well as case of approaching same chunk in world from different sides (exploring world left to right can yield different generation result when exploring from right to left, and this is not something that can be fixed, unless world is pre-generated in its entirety).

Behavior

universe_server.config

  • Added useNewWireProcessing, which defaults to true
    • New wire updating system is insanely fast (because wiring is updated along entity ticking, and doesn't involve intense entity map lookups)
    • However, it is not a complete replacement for legacy system, because some mods might rely on fact that in legacy system when wired entities update, they load all other endpoints into memory (basically, chunkload all connected entities). In new system if wired entity references unloaded entities it simply does not update its state.
    • If specified as false, original behavior will be restored, but beware of performance degradation! If you are a modder, PLEASE consider other ways around instead of enabling the old behavior, because performance cost of using old system is almost always gonna outweight "benefits" of chunkloaded wiring systems.

Plant drop entities (vines or steps dropping on ground)

  • Collision is now determined using hull instead of rectangle

Technical differences

  • Lighting engine is based off original code, but is heavily modified, such as:
    • Before spreading point lights, potential rectangle is determined, to reduce required calculations
    • Lights are clasterized, and clusters are processed together, on different threads (multithreading)
    • Point lights are being spread along both diagonals, not only along left-right bottom-top diagonal (can be adjusted using "light quality" setting)
    • While overall performance is marginally better than original game, and scales up to any number of cores, efficiency of spreading algorithm is worse than original
  • Chunk rendering is split into render regions, which size can be adjusted in settings
    • Increasing render region size will decrease CPU load when rendering world and increase GPU utilization efficiency, while hurting CPU performance on chunk updates, and vice versa
    • Render region size themselves align with world borders, so 3000x2000 world would have 30x25 sized render regions