From 4433e19b6361c02dd5cb23c947cd935ad87771a8 Mon Sep 17 00:00:00 2001 From: Ronja Date: Wed, 26 Jan 2022 21:01:53 +0100 Subject: [PATCH] add docs --- api/modifier/trail.wren | 152 +++++++++++++++++++++++++++--- assets/modifier/trail.modifier.lx | 1 + 2 files changed, 139 insertions(+), 14 deletions(-) diff --git a/api/modifier/trail.wren b/api/modifier/trail.wren index 1c5548b..dc2b8f3 100644 --- a/api/modifier/trail.wren +++ b/api/modifier/trail.wren @@ -2,7 +2,7 @@ import "luxe: io" for IO import "luxe: world" for World, Entity, Modifiers, ModifierSystem, Transform import "luxe: draw" for Draw, PathStyle, LineCap import "luxe: color" for Color -import "luxe: render" for Geometry, Primitive, IndexType, Render +import "luxe: render" for Geometry, Primitive, IndexType, Render, Material import "luxe: assets" for Assets, Strings import "luxe: bytes" for Uint16, Floats import "luxe: math" for Math @@ -11,83 +11,202 @@ import "trail: _queue" for Queue import "trail: modifier/trail.modifier" for ModifierData -//User facing API -//This is what the user of your modifier will interact with -class Trail { +#doc=""" + Modifier to add simple trails to entities. + Needs a Transform on the same entity to work. + ```js + var entity = Entity.create(world) + Transform.create(entity) + Trail.create(entity) + + //now just move and rotate the entity around + ``` +""" +class Trail { + static time_based{true} + static distance_based{false} + + #doc="Add a trail modifier to an entity. Entity should also have a Transform." + #args=( + entity = "The entity to add the trail modifier to." + ) static create(entity: Entity): None { Modifiers.create(This, entity) } + #doc="Remove the trail modifier from an entity." + #args=( + entity = "The entity to remove the trail modifier from." + ) static destroy(entity: Entity): None { Modifiers.destroy(This, entity) - - } - static has(entity: Entity): None { - Modifiers.has(This, entity) } + #doc="Check whether an entity has a trail modifier or not." + #args=( + entity = "The entity to check whether it has a trail modifier." + ) + static has(entity: Entity): Bool { + return Modifiers.has(This, entity) + } + + #doc="Reset trail to no length." + #args=( + entity = "The entity with the trail modifier." + ) static reset(entity: Entity): None { Modifiers.get_system(This, entity).reset(entity ) } + #doc="Set the width of a trail." + #args=( + entity = "The entity with the trail modifier.", + width = "The new width of the trail." + ) static set_width(entity: Entity, width: Num): None { Modifiers.get(This, entity).edge_length = width } + #doc="Get the width of a trail." + #args=( + entity = "The entity with the trail modifier." + ) static get_width(entity: Entity): Num { return Modifiers.get(This, entity).edge_length } + #doc="Set the length of a trail." + #args=( + entity = "The entity with the trail modifier.", + length = "The new length of the trail." + ) static set_length(entity: Entity, length: Num): None { Modifiers.get(This, entity).length = length //todo: recalculate transient data? } + #doc="Get the length of a trail." + #args=( + entity = "The entity with the trail modifier." + ) static get_length(entity: Entity): Num { return Modifiers.get(This, entity).length } - static set_time_based(entity: Entity, time_based: Num): None { + #doc=""" + Set whether the trail is time based or distance based. + + ```js + Trail.set_time_based(entity, Trail.distance_based) + ``` + """ + #args=( + entity = "The entity with the trail modifier.", + time_based = "`true` if its time based, `false` if its distance based." + ) + static set_time_based(entity: Entity, time_based: Bool): None { Modifiers.get(This, entity).time_based = time_based } - static get_time_based(entity: Entity): Num { + #doc=""" + Get whether the trail is time based or distance based. (true if time based, false if distance based) + """ + #args=( + entity = "The entity with the trail modifier." + ) + static get_time_based(entity: Entity): Bool { return Modifiers.get(This, entity).time_based } - static set_normalize_uvs(entity: Entity, normalize_uvs: Num): None { + #doc=""" + Set whether the trail should have normalized UVs of a trail. + If the UVs are normalized, they should be linear over distance, + especially with time based trails you otherwise can get very wobbly behaviour as speed changes. + """ + #args=( + entity = "The entity with the trail modifier.", + length = "Whether the trail should have normalized uvs." + ) + static set_normalize_uvs(entity: Entity, normalize_uvs: Bool): None { Modifiers.get(This, entity).normalize_uvs = normalize_uvs } - static get_normalize_uvs(entity: Entity): Num { + #doc="Get whether a trail has normalized uvs." + #args=( + entity = "The entity with the trail modifier." + ) + static get_normalize_uvs(entity: Entity): Bool { return Modifiers.get(This, entity).normalize_uvs } + #doc="Set the material the trail is rendered with via its id." + #args=( + entity = "The entity with the trail modifier." + ) static set_material_id(entity: Entity, material_id: String): None { Strings.add(material_id) Modifiers.get(This, entity).material = material_id - Modifiers.get_system(This, entity).set_material(entity, material_id) + Modifiers.get_system(This, entity).set_material_id(entity, material_id) } + #doc="Set the material the trail is rendered with." + #args=( + entity = "The entity with the trail modifier." + ) + static set_material(entity: Entity, material: Material): None { + var material_id = Material.get_source_id(material) + Strings.add(material_id) + Modifiers.get(This, entity).material = material_id + Modifiers.get_system(This, entity).set_material(entity, material) + } + + #doc="Get the id of the currently used material." + #args=( + entity = "The entity with the trail modifier." + ) static get_material_id(entity: Entity): String { return Strings.get(Modifiers.get(This, entity).material) } + #doc=""" + Set mesh subdivisions around length of the trail. + This will rebuild the mesh entirely and potentially throw away custom materials you set via `set_material`. + """ + #args=( + entity = "The entity with the trail modifier.", + subdivisions = "Subdivisions along length." + ) static set_subdivisions_length(entity: Entity, subdivisions: Num){ Modifiers.get(This, entity).subdivisions_length = subdivisions Modifiers.get_system(This, entity).recreate_buffers(entity) } + #doc="Get subdivisions in length of trail." + #args=( + entity = "The entity with the trail modifier." + ) static get_subdivisions_length(entity: Entity): Num{ return Modifiers.get(This, entity).subdivisions_length } + #doc=""" + Set mesh subdivisions around length of the trail. + This will rebuild the mesh entirely and potentially throw away custom materials you set via `set_material`. + """ + #args=( + entity = "The entity with the trail modifier.", + subdivisions = "Subdivisions along width." + ) static set_subdivisions_width(entity: Entity, subdivisions: Num){ Modifiers.get(This, entity).subdivisions_width = subdivisions Modifiers.get_system(This, entity).recreate_buffers(entity) } + #doc="Get subdivisions in width of trail." + #args=( + entity = "The entity with the trail modifier." + ) static get_subdivisions_width(entity: Entity): Num{ return Modifiers.get(This, entity).subdivisions_width } @@ -143,6 +262,7 @@ class TrailData { //This speaks to the engine and your user facing API //to do the actual work. You'll get notified when things change //in the world and respond to them here. +#hidden class TrailSystem is ModifierSystem { construct new() { @@ -175,8 +295,12 @@ class TrailSystem is ModifierSystem { _instance_data[entity].points.clear() } - set_material(entity: Entity, material_id: String){ + set_material_id(entity: Entity, material_id: String){ var material = Assets.material(material_id) + set_material(entity, material) + } + + set_material(entity: Entity, material: Material){ var data = _instance_data[entity] if(!data || !material) return Geometry.set_material(entity, material) diff --git a/assets/modifier/trail.modifier.lx b/assets/modifier/trail.modifier.lx index dc39602..c07d156 100644 --- a/assets/modifier/trail.modifier.lx +++ b/assets/modifier/trail.modifier.lx @@ -4,6 +4,7 @@ modifier = { field = "trail" display = "Trail" //the display in the editor class = "Trail" //The code generated name for the modifier API + dependency = ["luxe: modifier/transform"] block = { //The data for the modifiers fields = [ { name="edge_length" type="number" default=100 }