Limon Engine C++ API Reference
Animation
uint32_t animateModel(uint32_t modelID, uint32_t animationID, bool looped, const std::string& soundPath = “”)
Applies a custom animation to a model. Returns model handle ID.
Parameters:
uint32_t modelID: handle ID of the model to animate
uint32_t animationID: handle ID of the animation
bool looped: whether the animation is looped or one off.
const std::string& soundPath: path of the sound to play while the animation runs. If empty (default), no sound plays. Otherwise the sound will be played in a loop until the animation stops.
std::string getModelAnimationName(uint32_t modelID)
Returns current “Asset” animation name of the model. If a custom animation is applied to the model, it is not returned. Returns empty string when model is not found.
Parameters:
uint32_t modelID: handle ID of the model to check for animation name
Note
Asset Animation names are not managed by Limon, so it is possible empty string to be name of an animation.
bool getModelAnimationFinished(uint32_t modelID)
Returns true if model finished playing animation. For looped animations always returns false. Also returns false if model is not found.
Parameters:
uint32_t modelID: handle ID of the model to check for animation state
float getModelAnimationProgress(uint32_t modelID)
Returns the normalized progress [0.0, 1.0] of the custom animation currently running on the model (started via animateModel). For looped animations the value wraps back to 0.0 at the end of each cycle. Returns 0.0 if the model has no active custom animation or is not found.
Parameters:
uint32_t modelID: handle ID of the model
std::vector<std::string> listModelAnimations(uint32_t modelID)
Returns the names of all animations embedded in the model’s asset file. These names can be passed to setModelAnimation. Returns an empty vector if the model is not found.
Parameters:
uint32_t modelID: handle ID of the model
bool setModelAnimation(uint32_t modelID, const std::string& animationName, bool isLooped = true)
Applies an “Asset” animation to a model. Returns false if model is not found.
Parameters:
uint32_t modelID: handle ID of the model to animate
const std::string& animationName: Name of the animation to play
bool isLooped: Whether play animation and stop, or play in a loop
bool setModelAnimationWithBlend(uint32_t modelID, const std::string& animationName, bool isLooped = true, uint64_t blendTime = 100)
Applies an “Asset” animation to a model, blending it (using linear interpolation) with the previous animation. Returns false if model is not found.
Parameters:
uint32_t modelID: handle ID of the model to animate
const std::string& animationName: Name of the animation to play
bool isLooped: Whether play animation and stop, or play in a loop
uint64_t blendTime: How long (in milliseconds) the previous animation will influence the blended state.
bool setModelAnimationSpeed(uint32_t modelID, float speed)
Changes animation speed by given factor. speed=2.0 will double the animation speed. Speed values < 0.001f will be rejected and return false. If model is not found it will return false.
Parameters:
uint32_t modelID: handle ID of the model to animate
float speed: Animation time multiplier
std::vector<uint32_t> getModelChildren(uint32_t modelID)
Returns a vector of IDs with all children of model. Returns empty list for Model not found, as well as no children found.
Parameters:
uint32_t modelID: handle ID of the model to check for children
GUI Methods
uint32_t addGuiText(const std::string &fontFilePath, uint32_t fontSize, const std::string &name, const std::string &text, const glm::vec3 &color, const glm::vec2 &position, float rotation)
Adds GUI Text to world. Returns created GUITexts handle ID.
Parameters:
const std::string &fontFilePath: Font file to use while rendering the text.
uint32_t fontSize: Font size
const std::string &name: Name of the GameObject GUIText
const std::string &text: Text to render
const glm::vec3 &color: Text color. Values should be between 0 and 256.
const glm::vec2 &position: Position of the Text. This values will be between 0 and 1. 0,0 means left bottom and 1,1 means right top
float rotation: Rotation of the text. 0 is upwards. it is in rads and clockwise.
uint32_t addGuiImage(const std::string &imageFilePath, const std::string &name, const glm::vec2 &position, const glm::vec3 &scale, float rotation)
Adds GUI Image to world. Returns created GUIImage handle ID.
Parameters:
const std::string &imageFilePath: Image files path.
const std::string &name: Name of the GameObject GUIImage
const glm::vec2 &position: Position of the Text. This values will be between 0 and 1. 0,0 means left bottom and 1,1 means right top
const glm::vec2 &scale: scale of the image.
float rotation: Rotation of the text. 0 is upwards. it is in rads and clockwise.
bool updateGuiText(uint32_t guiTextID, const std::string &newText)
Updates rendered text of the GUIText provided by the handle ID. Returns true if successful, false if handle ID invalid.
Parameters:
uint32_t guiTextID
const std::string &newText
bool removeGuiElement(uint32_t guiElementID)
Removes the GUI element indicated by the handle ID. Returns true for success, false for invalid handle ID.
Parameters:
uint32_t guiElementID: GUI element handle ID
LimonTypes::Vec4 getGuiElementPosition(uint32_t guiElementID)
Returns the screen position of the GUI element as Vec4 (x, y, 0, 1). Coordinates are in the same screen-space range used by addGuiText and addGuiImage. Returns zero Vec4 if the element is not found.
Parameters:
uint32_t guiElementID: GUI element handle ID
bool setGuiElementPosition(uint32_t guiElementID, const LimonTypes::Vec4& position)
Sets the screen position of a GUI element. The x and y components are used; z and w are ignored. Returns false if the element is not found.
Parameters:
uint32_t guiElementID: GUI element handle ID
const LimonTypes::Vec4& position: Target position. x and y are screen-space coordinates.
bool setGuiElementVisible(uint32_t guiElementID, bool visible)
Shows or hides a GUI element without removing it. Hidden elements are not rendered but remain in the world and can be made visible again. Returns false if the element is not found.
Parameters:
uint32_t guiElementID: GUI element handle ID
bool visible: true to show, false to hide
Object Manipulation
uint32_t addObject(const std::string &modelFilePath, float modelWeight, bool physical, const glm::vec3 &position, const glm::vec3 &scale, const glm::quat &orientation)
Adds Model to world. Returns created Model handle ID.
Parameters:
const std::string &modelFilePath: Model files path.
float modelWeight: Weight of the model. 0 means object is static, and it won’t move.
bool physical: Whether model has physical interactions or not. If set to false, it won’t collide with anything.
const glm::vec3 &position: World position of the Object. Please note some objects has their center set to their feet.
const glm::vec3 &scale: scale of the object.
const glm::quat &orientation: Rotation of the model.
bool attachObjectToObject(uint32_t objectID, uint32_t objectToAttachToID)
Attaches object indicated by the handle ID, to another object indicated by second parameter. Returns true for success, false for invalid Handle ID for either parameter. Attachment means if parent object move, child will move too. Example usage: bullet hole decals to dynamic objects. The object should have a transformation relative to the object it will be attached.
Parameters:
uint32_t objectID: handle id of the object to attach as child.
uint32_t objectToAttachToID: handle id of the object to attach as parent.
bool attachObjectToObjectAtWorldPosition(uint32_t objectID, uint32_t objectToAttachToID)
Attaches object indicated by the handle ID to another object, using the object’s current world-space position as the attachment offset. This is equivalent to attachObjectToObject, but instead of using a pre-set relative transform the engine computes the offset from the child’s current world position at the moment of attachment. Returns true for success, false for invalid handle ID for either parameter.
Parameters:
uint32_t objectID: handle id of the object to attach as child.
uint32_t objectToAttachToID: handle id of the object to attach as parent.
bool setObjectTemporary(uint32_t objectID, bool temporary)
Changes objects temporary flag. If an object is temporary, it won’t be saved with map save. There is no other difference. Returns false if object can’t be found. Returns true if successful.
Parameters:
uint32_t objectID: handle id of the object to change flag.
bool temporary: whether flag is set or not. True value will prevent save with the map.
std::vector<LimonTypes::GenericParameter> getObjectTransformation(uint32_t objectID)
returns objects transformation information. If the object ID is valid, the returned vector will contain 3 vec4 parameters, translate, scale, orientation in respective order. For translate and scale, w component is not used. Orientation is in quaternion form. Returns empty vector if object not found.
Note
Prefer getObjectTransformationMatrix when you need the final world matrix. Physical objects can define collision-shape offsets that are baked into the matrix but are not reflected in the decomposed translate/scale/orientation values returned here. Use this method only when you specifically need the individual TRS components.
Parameters:
uint32_t objectID: handle id of the object to get transformation.
std::vector<LimonTypes::GenericParameter> getObjectTransformationMatrix(uint32_t objectID)
returns objects transformation matrix. If object has custom matrix generation (Physical object can define offsets), transformation might not be enough to build the matrix. This method provides objects matrix as Limon Engine has it. Returns empty vector if object not found.
Parameters:
uint32_t objectID: handle id of the object to get transformation matrix.
bool setObjectTranslate(uint32_t objectID, const LimonAPI::Vec4& position)
Sets objects world position to 2. parameter. Returns false if object is not found.
Parameters:
uint32_t objectID: handle id of the object to change position.
const LimonAPI::Vec4& position: new position of the object
Note
Fourth element in the vector is ignored.
bool setObjectScale(uint32_t objectID, const LimonAPI::Vec4& scale)
Sets objects scale to 2. parameter. Returns false if object is not found.
Parameters:
uint32_t objectID: handle id of the object to change scale.
const LimonAPI::Vec4& scale: new scale of the object
Note
Fourth element in the vector is ignored.
bool setObjectOrientation(uint32_t objectID, const LimonAPI::Vec4& orientation)
Sets object world orientation to 2. parameter, aka rotates it. Returns false if object is not found.
Parameters:
uint32_t objectID: handle id of the object to change orientation.
const LimonAPI::Vec4& orientation: new orientation of the object
bool addObjectTranslate(uint32_t objectID, const LimonAPI::Vec4& position)
Adds given vector to objects current world position, effectively moving it. Returns false if object is not found.
Parameters:
uint32_t objectID: handle id of the object to change position.
const LimonAPI::Vec4& position: position change desired for the object
Note
Fourth element in the vector is ignored.
bool addObjectScale(uint32_t objectID, const LimonAPI::Vec4& scale)
Scales the object, in respect to its current scale. If object is scaled to double of its original size before this call, and this call scales it to half, object will be at its original size afterwards. Returns false if object is not found.
Parameters:
uint32_t objectID: handle id of the object to change scale.
const LimonAPI::Vec4& scale: scale of object in respect to current scale.
Note
Fourth element in the vector is ignored.
bool addObjectOrientation(uint32_t objectID, const LimonAPI::Vec4& orientation)
Rotates the object from current orientation. Returns false if object ID not found.
Parameters:
uint32_t objectID: handle id of the object to change orientation.
const LimonAPI::Vec4& orientation: new orientation of the object
bool removeObject(uint32_t objectID, const bool &removeChildren = true)
Removes object indicated by the handle ID passed. Returns true for success, false for invalid Handle ID.
Parameters:
uint32_t objectID: handle id of the object to remove.
const bool &removeChildren: if true, child objects are also removed. Defaults to true.
bool removeTriggerObject(uint32_t triggerObjectID)
Removes trigger volume indicated by the handle ID passed. Returns true for success, false if trigger handle ID invalid.
Parameters:
uint32_t triggerObjectID: handle id of the trigger volume to remove.
LimonTypes::Vec4 getObjectLinearVelocity(uint32_t objectID)
Returns the linear velocity of the object’s rigid body as a Vec4 (w=0). Returns a zero Vec4 if the object is not found or has no rigid body.
Parameters:
uint32_t objectID: Handle ID of the model.
bool setObjectLinearVelocity(uint32_t objectID, const LimonTypes::Vec4& velocity)
Sets the linear velocity of the object’s rigid body. Wakes the body if sleeping. Returns false if the object is not found or has no rigid body.
Parameters:
uint32_t objectID: Handle ID of the model.
const LimonTypes::Vec4& velocity: Desired velocity in world space (w is ignored).
float getObjectMass(uint32_t objectID)
Returns the mass of the object in kilograms. Returns 0.0 for static objects or if the object is not found.
Parameters:
uint32_t objectID: Handle ID of the model.
bool disconnectObjectFromPhysics(uint32_t modelID)
Disconnects the model from physics, but it will be rendered as usual. Including custom and asset builtin animations. Returns true for success, false for fail. Fail can be either Handle ID invalid or the object is not a model, and can’t be disconnected.
Parameters:
uint32_t modelID: handle id of the model to disconnect.
bool reconnectObjectToPhysics(uint32_t modelID)
Connects the model from physics. Returns true for success, false for fail. Fail can be either Handle ID invalid or the object is not a model, and can’t be connected. Does nothing if already connected, returns true.
Parameters:
uint32_t modelID: handle id of the model to connect.
bool applyForce(uint32_t modelID, const LimonAPI::Vec4 &forcePosition, const LimonAPI::Vec4 &forceAmount)
Applies force to object using physics engine. This method have effect on only dynamic objects. Returns false if object is not found.
Parameters:
uint32_t modelID: handle id of the model to apply force to.
const LimonAPI::Vec4 &forcePosition: World position for the force vector to originate. Raycast results can be used for this method. Only 3 components of this method will be used, w component will be ignored.
const LimonAPI::Vec4 &forceAmount: Force vector. Only 3 components of this method will be used, w component will be ignored.
bool applyForceToPlayer(const LimonAPI::Vec4 &forceAmount)
Applies force to player using physics engine. Returns false if physical player is not used in this world(map).
Parameters:
const LimonAPI::Vec4 &forceAmount: Force vector. Only 3 components of this method will be used, w component will be ignored.
bool isInsideTrigger(uint32_t triggerID)
Returns whether a player is currently inside the trigger volume.
Parameters:
uint32_t triggerID: The handleID of the trigger object
Returns true if the player is inside the volume, false if not or if the trigger ID is not found.
std::vector<LimonTypes::GenericParameter> getResultOfTrigger(uint32_t triggerObjectID, uint32_t triggerCodeID)
Returns the result of the trigger object. For details, check trigger object editor
Parameters:
uint32_t triggerObjectID: The handleID of trigger object
uint32_t triggerCodeID: Which triggers result is requested. 1-> first enter, 2-> enter, 3-> exit.
uint32_t getObjectByName(const std::string& name)
Searches all models, GUI elements, and trigger objects by name and returns the world object ID of the first match.
Parameters:
const std::string& name: The name to search for. For models this is
modelName_ID(as shown in the editor). For triggers it is the trigger name.
Returns the object ID if found, 0 if not found.
uint32_t getObjectParent(uint32_t objectID)
Returns the world object ID of the parent of the given object.
Parameters:
uint32_t objectID: The handleID of the object whose parent is requested
Returns the parent object ID, or 0 if the object has no parent or is not found.
bool isObjectPhysicsConnected(uint32_t objectID)
Returns whether the object is currently active in the physics simulation. Objects can be disconnected from physics via disconnectObjectFromPhysics and reconnected via reconnectObjectToPhysics.
Parameters:
uint32_t objectID: The handleID of the object
Returns true if physics-connected, false if disconnected or not found.
Sound
bool attachSoundToObjectAndPlay(uint32_t objectWorldID, const std::string &soundPath, bool looped = true)
Warning
Removed. Sound is now a first-class game object with full attachment support. Use playSound to create the sound and obtain its ID, then use attachObjectToObject to attach it to the target model. Stop and remove it with stopSound.
// Before (no longer available)
limonAPI->attachSoundToObjectAndPlay(modelID, "sound.wav", true);
// After
uint32_t soundID = limonAPI->playSound("sound.wav", glm::vec3(0,0,0), false, true);
limonAPI->attachObjectToObject(soundID, modelID);
bool detachSoundFromObject(uint32_t objectWorldID)
Warning
Removed. Now that attachSoundToObjectAndPlay has been replaced with the playSound + attachObjectToObject flow, the sound ID is available and stopSound serves as the direct replacement.
uint32_t playSound(const std::string &soundPath, const glm::vec3 &position, bool positionRelative = false, bool looped = false, float referenceDistance = 2.0f, float maxDistance = 50.0f)
Creates and plays a sound at a world position. Returns the sound ID used to control playback. Returns 0 on failure.
Parameters:
const std::string &soundPath: Path of the sound to play.
const glm::vec3 &position: World position of the sound source.
bool positionRelative: If true, position is relative to the listener (camera). Defaults to false.
bool looped: Play once or play in a loop. Defaults to false.
float referenceDistance: Distance at which the sound plays at full volume. Below this distance gain is clamped to maximum. Defaults to 2.0.
float maxDistance: Distance at which the sound is fully attenuated and becomes inaudible. Defaults to 50.0.
Note
Only mono audio files are spatialized by OpenAL. Stereo files play at a fixed volume regardless of position.
bool stopSound(uint32_t soundID)
Stops a playing sound and removes it from the world. Returns false if the sound ID is not found.
Parameters:
uint32_t soundID: The ID returned by playSound.
bool pauseSound(uint32_t soundID)
Pauses a playing sound without stopping it. The sound can be resumed with resumeSound. Returns false if the sound ID is not found.
Parameters:
uint32_t soundID: The ID returned by playSound.
bool resumeSound(uint32_t soundID)
Resumes a paused sound from where it left off. Returns false if the sound ID is not found.
Parameters:
uint32_t soundID: The ID returned by playSound.
bool setSoundVolume(uint32_t soundID, float volume)
Sets the volume (gain) of a sound. Returns false if the sound ID is not found or the sound has not started playing yet.
Parameters:
uint32_t soundID: The ID returned by playSound.
float volume: New gain value.
bool setSoundLooped(uint32_t soundID, bool looped)
Changes whether a sound loops after the current play-through. Can be used to transition a looping sound into a one-shot that stops after the current cycle. Returns false if the sound ID is not found.
Parameters:
uint32_t soundID: The ID returned by playSound.
bool looped: True to loop, false to stop after the current play-through.
bool isSoundPlaying(uint32_t soundID)
Returns true if the sound is currently playing or finishing a non-looped play-through. Returns false if not found.
Parameters:
uint32_t soundID: The ID returned by playSound.
Player
LimonTypes::Vec4 getPlayerPosition()
Returns the player’s current world position as a Vec4 (w=1).
Parameters:
none
LimonTypes::Vec4 getPlayerLookDirection()
Returns the player’s normalized look direction as a Vec4 (w=0).
Parameters:
none
LimonTypes::Vec4 getCameraPosition()
Returns the camera’s world position as a Vec4 (w=1). This comes from the active camera attachment - if a PlayerExtensionInterface overrides the camera attachment, this value may differ from getPlayerPosition.
Parameters:
none
LimonTypes::Vec4 getCameraLookDirection()
Returns the camera’s normalized look direction as a Vec4 (w=0). This comes from the active camera attachment - if a PlayerExtensionInterface overrides the camera attachment, this value may differ from getPlayerLookDirection.
Parameters:
none
uint32_t getPlayerAttachedModel()
Returns the model ID of player attachment. return 0 if player has no attachment.
Parameters:
none
Note
Player attachment might have children, check getModelChildren method
LimonAPI::Vec4 getPlayerAttachedModelOffset()
Returns offset of the model attached to player. returns Vec4(0,0,0,0) if player has no attachment.
Parameters:
none
bool setPlayerAttachedModelOffset(LimonAPI::Vec4 newOffset)
Sets offset to player attachment. Returns false if player has no attachment.
Parameters:
LimonAPI::Vec4: offset to set. w component of parameter ignored.
void interactWithPlayer(std::vector<LimonTypes::GenericParameter> &interactionInformation)
Sends the interaction information to player Extension. If no extension is loaded, it will not have any effect.
Parameters:
std::vector<LimonTypes::GenericParameter> &interactionInformation: Parameters to pass.
void killPlayer()
Kills the player.
Parameters:
none
bool interactWithAI(uint32_t AIID, std::vector<LimonTypes::GenericParameter> &interactionInformation)
Sends the parameters to AI as new interaction. Since AI is an extension point, the parameters required are not defined by Limon engine. Returns false if no AI actor with given ID found.
Parameters:
uint32_t AIID: ID of AI actor to send the data
std::vector<LimonTypes::GenericParameter> &interactionInformation: Parameters to pass.
Particle Systems
uint32_t addParticleEmitter(const std::string &name, const std::string &textureFile, const LimonTypes::Vec4 &startPosition, const LimonTypes::Vec4 &maxStartDistances, const LimonTypes::Vec2 &size, uint32_t count, uint32_t lifeTime, float particlePerMs, bool continuouslyEmit)
Creates a new particle emitter in the world and returns its handle ID.
Parameters:
const std::string &name: Name of the emitter.
const std::string &textureFile: Path to the texture used for each particle.
const LimonTypes::Vec4 &startPosition: World-space origin of the emitter. W component ignored.
const LimonTypes::Vec4 &maxStartDistances: Maximum random offset applied to each particle’s spawn position. W component ignored.
const LimonTypes::Vec2 &size: Width and height of each particle billboard.
uint32_t count: Maximum number of live particles at any time.
uint32_t lifeTime: How long each particle lives, in milliseconds.
float particlePerMs: How many particles are spawned per millisecond.
bool continuouslyEmit: If true the emitter keeps spawning particles indefinitely; if false it emits one burst of
countparticles and stops.
bool removeParticleEmitter(uint32_t emitterID)
Removes the particle emitter indicated by the handle ID. Returns true on success, false if the ID is not found.
Parameters:
uint32_t emitterID: Handle ID of the emitter to remove.
bool enableParticleEmitter(uint32_t particleEmitterId)
Resumes a previously disabled particle emitter. Returns true on success, false if the ID is not found.
Parameters:
uint32_t particleEmitterId: Handle ID of the emitter to enable.
bool disableParticleEmitter(uint32_t particleEmitterId)
Pauses a particle emitter so it stops spawning new particles. Existing live particles continue until their lifetime expires. Returns true on success, false if the ID is not found.
Parameters:
uint32_t particleEmitterId: Handle ID of the emitter to disable.
bool setEmitterParticleSpeed(uint32_t emitterID, const LimonTypes::Vec4 &speedMultiplier, const LimonTypes::Vec4 &speedOffset)
Sets the speed parameters for particles spawned by the emitter. speedMultiplier scales the base velocity and speedOffset adds a constant velocity component. Returns false if the emitter ID is not found.
Parameters:
uint32_t emitterID: Handle ID of the emitter.
const LimonTypes::Vec4 &speedMultiplier: Per-axis scale applied to the particle’s initial velocity. W component ignored.
const LimonTypes::Vec4 &speedOffset: Constant velocity added to every particle on spawn. W component ignored.
bool setEmitterParticleGravity(uint32_t emitterID, const LimonTypes::Vec4 &gravity)
Sets the gravity vector applied to particles spawned by the emitter each tick. Returns false if the emitter ID is not found.
Parameters:
uint32_t emitterID: Handle ID of the emitter.
const LimonTypes::Vec4 &gravity: Per-axis acceleration applied each frame. W component ignored.
Lighting
uint32_t addLight(uint32_t lightType, const LimonAPI::Vec4& position, const LimonAPI::Vec4& color)
Creates and adds a new light to the world. Returns the new light’s handle ID, or 0 on failure.
lightType values:
1- Directional light (position parameter is used as direction, normalized internally)2- Point light
Parameters:
uint32_t lightType: Type of light to create. 1 = directional, 2 = point.
const LimonAPI::Vec4& position: World position for point lights; direction vector for directional lights. W component ignored.
const LimonAPI::Vec4& color: RGB color of the light. Each component is clamped to [0, 1]. W component ignored.
bool removeLight(uint32_t lightID)
Removes the light indicated by lightID. Properly shuts down visibility threads associated with the light’s shadow cameras before deletion. Returns true on success, false if no light with the given ID is found.
Parameters:
uint32_t lightID: Handle ID of the light to remove.
bool addLightTranslate(uint32_t lightID, const LimonAPI::Vec4& translate)
Adds given translate to current position of the light indicated by the lightID. Returns false if no light with given ID found.
Parameters:
uint32_t lightID: ID of light to translate
const LimonAPI::Vec4& translate: Translate vector to add. W component will be ignored.
bool setLightColor(uint32_t lightID, const LimonAPI::Vec4& color)
Sets the color of the light, indicated by lightID parameter. Returns false if no light with given ID found.
Parameters:
uint32_t lightID: ID of light to change color
const LimonAPI::Vec4& color: RGB color to set. W component will be ignored.
LimonTypes::Vec4 getLightPosition(uint32_t lightID)
Returns the world-space position of the light as Vec4 with w=1. Returns zero Vec4 if no light with the given ID is found.
Parameters:
uint32_t lightID: Handle ID of the light
LimonTypes::Vec4 getLightColor(uint32_t lightID)
Returns the color of the light as Vec4 with w=1. Returns zero Vec4 if no light with the given ID is found.
Parameters:
uint32_t lightID: Handle ID of the light
bool setLightTranslate(uint32_t lightID, const LimonTypes::Vec4& position)
Sets the absolute world-space position of a light. Unlike addLightTranslate, this replaces the current position rather than adding to it. Returns false if no light with the given ID is found.
Parameters:
uint32_t lightID: Handle ID of the light
const LimonTypes::Vec4& position: Target world-space position. W component will be ignored.
World Management
bool loadAndSwitchWorld(const std::string& worldFileName)
Loads a world file, then switches the current world to the newly loaded one. If the world file was already loaded, removes the old one, effectively resetting the world. Returns false if the world file couldn’t be loaded, or it is the current world. Since caller is part of current world, removing it is not possible.
Parameters:
const std::string& worldFileName: The file path+name of the world to load.
bool returnToWorld(const std::string& worldFileName)
Checks if the world file is loaded. If it is not, loads the world. Then changes the current world to requested one. Returns false if the world file couldn’t be loaded.
Parameters:
const std::string& worldFileName: The file path+name of the world to load.
bool loadAndRemove(const std::string& worldFileName)
Loads the world requested, and removes the current world. Returns true if load successful, false if not. If not successful, world doesn’t change.
It is used to switch between big worlds, like game maps. It is not necessary to clear menu worlds since they use very little memory.
Note
This method clears the return previous world stack.
Parameters:
const std::string& worldFileName: The file path+name of the world to load.
void returnPreviousWorld()
Returns to the world that was running before current. If no world is found, it will be a noop.
Parameters:
none
void quitGame()
Clears the open devices and quits the game, shutting down the engine process.
bool changeRenderPipeline(const std::string& pipelineFileName)
Changes the current rendering pipeline to the one specified by the given file.
Parameters:
const std::string& pipelineFileName: The filename of the pipeline configuration to load
- Returns:
bool: True if the pipeline was changed successfully, false otherwise
const OptionsUtil::Options *getOptions()
Returns a pointer to the current options.
Variables
LimonTypes::GenericParameter& getVariable(const std::string& variableName)
Returns variable from global variable store. If the variable is never set, it will be 0 initialized. Returned reference can be updated, doing so will be setting the parameter.
The variables are accessible by all triggers, and there are no safety checks. User is fully responsible for use of them.
Warning
The variables are not saved with world itself, so they should be considered temporary.
Parameters:
const std::string& variableName: The name of the variable that should be returned.
std::vector<LimonTypes::GenericParameter> buildMultiSelect(const std::string& description, const std::vector<std::string>& options, size_t selectedIndex) (static inline)
Builds the parameter block that the editor expects for a MULTI_SELECT parameter. Returns a vector of GenericParameter objects: the first element holds the currently selected string; subsequent elements are one entry per option.
Append the returned vector to the extension’s parameter vector at the position where the multi-select should appear. For Triggers and Player Extensions that means seeding it into the parameters member in the constructor; for Actors it means appending it inside the overridden getParameters().
// Example: select which gun type the enemy carries
std::vector<LimonTypes::GenericParameter> gunOptions = LimonAPI::buildMultiSelect("Gun type", {"Pistol", "Rifle", "Shotgun"}, 0);
for(LimonTypes::GenericParameter& gunOption : gunOptions) {
this->parameters.push_back(gunOption);
}
Parameters:
const std::string& description: Display label shown in the editor. All generated parameters share this description - the editor uses it to group them.
const std::vector<std::string>& options: List of option strings.
size_t selectedIndex: Index into
optionsof the currently selected item. If out of range, the selection string is left empty.
Ray Casting
std::vector<LimonTypes::GenericParameter> rayCastToCursor()
Returns information about what is under player cursor (crosshair). If nothing is found, empty vector is returned. if something is hit, return vector will have the following information:
ObjectID of the hit object
hit coordinates
hit normal
if Object has AI, AI id. If not, this parameter will not be in the vector.
Parameters:
none
std::vector<LimonTypes::GenericParameter> rayCastFirstHit(const LimonTypes::Vec4& start, const LimonTypes::Vec4& direction)
Casts a ray from the given start position in the given direction and returns information about the first physics object hit. Returns an empty vector if nothing is hit.
If something is hit, the return vector contains the same fields as rayCastToCursor:
ObjectID of the hit object
hit coordinates
hit normal
if the object has AI, its AI id. Otherwise this parameter is absent.
Parameters:
const LimonTypes::Vec4& start: World-space ray origin. The w component is ignored.
const LimonTypes::Vec4& direction: Ray direction (need not be normalized). The w component is ignored.
Timed Events
long addTimedEvent(uint64_t waitTime, bool useWallTime, std::function<void(const std::vector<LimonTypes::GenericParameter>&)> methodToCall, std::vector<LimonTypes::GenericParameter> parameters)
Runs the given method, with passed parameters, after a given amount of time. Returns a handle ID that can be passed to cancelTimedEvent to cancel the event before it fires.
Parameters:
uint64_t waitTime: How long to wait before call, in milliseconds.
bool useWallTime: If true, real wall-clock time is used. If false, in-game time is used (pauses when the game is paused or a menu world is active).
std::function<void(const std::vector<LimonTypes::GenericParameter>&)> methodToCall: function to call.
std::vector<LimonTypes::GenericParameter> parameters: parameters passed to the function call.
- Returns:
long: A handle ID for the scheduled event. Pass it to cancelTimedEvent to cancel before it fires. Returns -1 on failure.
Note
Wait time is not precise beyond game ticks. Limon Engine internally ticks each 1/60 seconds.
Warning
If function is part of an object, and that object is removed, engine might crash. Avoiding those situations are game developers responsibility.
bool cancelTimedEvent(long handleId)
Cancels a previously scheduled timed event before it fires. Returns true if the event was found and cancelled, false if no event with the given handle ID exists.
Parameters:
long handleId: The handle ID returned by addTimedEvent.
Input
void simulateInput(const InputStates& input)
Simulates input events for testing or automation purposes.
Parameters:
const InputStates& input: The input state to simulate
Profiling
ProfileScope profileScope(const std::string& name)
Opens a named Tracy profiler zone and returns a ProfileScope RAII guard. The zone is closed automatically when the returned object goes out of scope.
{
auto scope = limonAPI->profileScope("MyTrigger::run");
// ... work being profiled ...
} // zone ends here
Parameters:
const std::string& name: Name shown in the Tracy profiler for this zone.
Logging
void log(Logger::Subsystem subsystem, Logger::Level level, const std::string& text)
Writes a message to the engine’s log system. The message will appear in the in-game log overlay (if enabled) and in the engine’s log output.
Parameters:
Logger::Subsystem subsystem: Which engine subsystem the message belongs to. Available values:
log_Subsystem_RENDER,log_Subsystem_MODEL,log_Subsystem_INPUT,log_Subsystem_SETTINGS,log_Subsystem_AI,log_Subsystem_LOAD_SAVE,log_Subsystem_EDITOR,log_Subsystem_ANIMATION.Logger::Level level: Severity of the message. Available values:
log_level_TRACE,log_level_DEBUG,log_level_INFO,log_level_WARN,log_level_ERROR.const std::string& text: The message text.
Debug Line Drawing
uint32_t drawDebugLine(const LimonTypes::Vec4& from, const LimonTypes::Vec4& to, const LimonTypes::Vec4& fromColor, const LimonTypes::Vec4& toColor, bool requireCameraTransform)
Creates a new debug line buffer containing one line segment and returns its buffer ID. The line persists across frames until the buffer is explicitly removed with clearDebugLines. Additional segments can be appended to the same buffer via addToDebugLine.
The typical per-frame pattern is: clear the previous buffer, then call drawDebugLine to create a fresh one.
Parameters:
const LimonTypes::Vec4& from: World-space start point of the line. The w component is ignored.
const LimonTypes::Vec4& to: World-space end point of the line. The w component is ignored.
const LimonTypes::Vec4& fromColor: RGB color at the start vertex. The w component is ignored.
const LimonTypes::Vec4& toColor: RGB color at the end vertex. The w component is ignored.
bool requireCameraTransform: Pass
truefor 3D world-space lines;falsefor screen-space (2D GUI) lines.
- Returns:
uint32_t: The new buffer’s ID. Pass this to
addToDebugLineorclearDebugLines.
bool addToDebugLine(uint32_t bufferIndex, const LimonTypes::Vec4& from, const LimonTypes::Vec4& to, const LimonTypes::Vec4& fromColor, const LimonTypes::Vec4& toColor, bool requireCameraTransform)
Appends a line segment to an existing debug line buffer. All segments in a buffer are rendered and cleared together.
Parameters:
uint32_t bufferIndex: ID of the buffer to append to, as returned by drawDebugLine.
const LimonTypes::Vec4& from: World-space start point of the segment. The w component is ignored.
const LimonTypes::Vec4& to: World-space end point of the segment. The w component is ignored.
const LimonTypes::Vec4& fromColor: RGB color at the start vertex. The w component is ignored.
const LimonTypes::Vec4& toColor: RGB color at the end vertex. The w component is ignored.
bool requireCameraTransform: Should match the value used when the buffer was created.
- Returns:
bool:
trueon success;falseifbufferIndexdoes not refer to an existing buffer.
bool clearDebugLines(uint32_t bufferIndex)
Removes a debug line buffer, hiding all line segments it contained.
Parameters:
uint32_t bufferIndex: ID of the buffer to remove, as returned by drawDebugLine.
- Returns:
bool:
trueon success;falseifbufferIndexdoes not refer to an existing buffer.