FANDOM


The goal of MagicLib is to create an Open Source, community driven "library" of useful scripts and plugins that can be leveraged and contributed to by everyone.

It can be found at its forum page
or Nexus Mods site


MagicAnimEdit

A collection of functions to make smooth animations.

MagicAnim smooth

SMOOTHEdit

(float) MagicAnim.smooth(float x)

Translates a value in a (0,1) range into a value in the same range with smooth ease-in and ease-out.

MagicAnim ARBITRARYSMOOTH

ARBITRARY SMOOTH (AS)Edit

(float) MagicAnim.AS (float x, float min, float max)

Translates a value in a (min,max) range into a value in the same range with smooth ease in and ease out.

MagicAnim SMOOTHOFFSET

SMOOTH+OFFSET (SO)Edit

(float) MagicAnim.SO (float x, float start, float end)

Translates a value in a (start,end) range into a (0,1) range with smooth ease in and ease out.

MagicAnim RETURNSMOOTHOFFSET

RETURN+SMOOTH+OFFSET (RSO)Edit

(float) MagicAnim.RSO (float x, float start, float end)

Translates a value in a (start,end) range into a "back and forth" value in a (0,1) range with smooth ease in and ease out.

MagicAnim OFFSET

OFFSETEdit

(float) MagicAnim.offset (float x, float start, float end)

Translates a value in a (start,end) range into a (0,1) range.

MagicAnim range

RANGEEdit

(float) MagicAnim.range (float x, float min, float max)

Translates a (0,1) value into a different (min,max) range.

Smooth+offset is the most useful function: if you have a "timer" source, say a weapon charge, you can add animation at specific points of the charge level. For example;

float doorX = MagicAnim.SO(weapon.getChargeLevel(),0.2f,0.7f)*4;
float doorY = MagicAnim.SO(weapon.getChargeLevel(),0.4f,1f)*11;

Means the value doorY will go from 0 to 11 between charge levels of 0.4 to 1, while the valuedoorX will move from 0 to 4 between charge levels of 0.2 to 0.7. Meaning the door will first move sideways then to the front with with a smooth arc.

MagicAnim SMOOTHplusOFFSET


Return+Smooth+Offset can be used with "locks" that open and close or to add staggers.

MagicFakeBeamEdit

Creates convincing ponctual beams from arbitrary coordinates.

MagicFakeBeam.spawnFakeBeam (
 CombatEngineAPI engine,
 Vector2f from,
 float range,
 float angle,
 float width,
 float full,
 float fading,
 float impactSize,
 Color core,
 Color fringe,
 float normalDamage,
 DamageType type,
 float emp,
 ShipAPI source
)

It however has several limitation:

  • - It deals damage instantly and is therefore only meant to be used for burst beams.
  • - It cannot be "cut" by another object passing between the two ends, thus a very short duration is preferable.
  • - Unlike vanilla, it deals full damage to armor, be careful when using HIGH_EXPLOSIVE damage type.
  • - While the colors can be set, the texture is smooth.

It's usage is recommended for short snappy beams or for VFXs

CODE EXAMPLE:

 MagicFakeBeam.spawnFakeBeam(
        engine,                         //combat engine
        missile.getLocation(),          //start point
        500,                            //beam range
        missile.getFacing(),            //aim
        8,                              //beam width
        0.1f,                           //beam duration
        0.2f+(float)Math.random()*0.2f, //beam fading
        100,                            //impact size
        Color.WHITE,                    //core color
        Color.BLUE,                     //impact color
        missile.getDamageAmount(),      //damage amount
        missile.getDamageType(),        //damage type
        missile.getEmpAmount(),         //emp amount
        missile.getSource()             //damage source
        );

Spawns a beam from a missile, used from a custom missile AI, to make laser torpedoes.
MagicFakeBeam spawnFakeBeam

MagicLensFlareEdit

Creates "cinematic" lensflares

ShartLensflare
MagicLensFlare.createSharpFlare (
 CombatEngineAPI engine,
 ShipAPI origin,
 Vector2f point,
 float thickness,
 float length,
 float angle,
 Color fringeColor,
 Color coreColor
)

Creates sharp lensflares, more suited to very thin short lived flares. Not CPU intensive.

(example requires LazyLib for MathUtils.getRandomPointInCircle)

CODE EXAMPLE:
MagicLensFlare.createSharpFlare(
        engine,
        ship,
        MathUtils.getRandomPointInCircle(
                ship.getLocation(),
                ship.getCollisionRadius()
                ),
        5,
        250,
        0,
        new Color(50,175,255),
        new Color(200,200,255)
        );
SmoothLensflare
MagicLensFlare.createSmoothFlare(
 CombatEngineAPI engine,
 ShipAPI origin,
 Vector2f point,
 float thickness,
 float length,
 float angle,
 Color fringeColor,
 Color coreColor
)

Creates smooth lensflares, more suited to thick and wide flares. Can be CPU intensive for larger flares.

(example requires LazyLib for MathUtils.getRandomPointInCircle)

CODE EXAMPLE:
MagicLensFlare.createSmoothFlare(
        engine,
        ship,
        MathUtils.getRandomPointInCircle(
                ship.getLocation(),
                ship.getCollisionRadius()
                ),
        50,
        400,
        0,
        new Color(50,175,255),
        new Color(200,200,255)
        );

MagicRenderEdit

Draw arbitrary sprites on screen with constraints to entities/camera when needed. Warning: those sprites will always be rendered on top of all the game's entities.

MagicRender.singleframe(
 SpriteAPI sprite,
 Vector2f loc,
 Vector2f size,
 float angle,
 Color color,
 boolean additive
)

Single frame render in absolute combat engine coordinates, can be used for animations.

MagicRender worldspace
MagicRender.battlespace(
 SpriteAPI sprite,
 Vector2f loc,
 Vector2f vel,
 Vector2f size,
 Vector2f growth,
 float angle,
 float spin,
 Color color,
 boolean additive,
 float fadein,
 float full,
 float fadeout
)    

Draws a sprite in absolute combat engine coordinates for a duration. Perfect for effects.

Use case example:
MagicRender battlespace2

MagicRender objectspace1
MagicRender.objectspace(
 SpriteAPI sprite,
 CombatEntityAPI anchor,
 Vector2f offset,
 Vector2f vel,
 Vector2f size,
 Vector2f growth,
 float angle,
 float spin,
 boolean parent,
 Color color,
 boolean additive,
 float fadein,
 float full,
 float fadeout,
 boolean fadeOnDeath
)  

Draws a sprite attached to an entity for a duration. When "parent" is true, the sprite will also be constrained by the anchor's orientation instead of only following the position. If "fadeOnDeath" is true, the sprite will fade out when the anchor dies or is removed, otherwise it will be instantly removed.

MagicLib screenspace
MagicRender.screenspace(
 SpriteAPI sprite,
 positioning pos,
 Vector2f loc,
 Vector2f vel,
 Vector2f size,
 Vector2f growth,
 float angle,
 float spin,
 Color color,
 boolean additive,
 float fadein,
 float full,
 float fadeout
)

Draws a sprite attached to the camera for a duration. Can be used to create UI elements. There are several positioning options:

CENTER:

The sprite will be drawn relative to the center of the screen.

LOW_LEFT, LOW_RIGHT, UP_LEFT, UP_RIGHT:

The sprite will be drawn relative to the relevant screen corner regardless of the user's resolution.

STRETCH_TO_FULLSCREEN:

The sprite will be stretched to full screen. Ignores loc, vel, size, growth, angle and spin.

FULLSCREEN_MAINTAIN_RATIO:

The sprite will be stretched to fill the screen while keeping the ratio of the "size" parameter. Ignores loc, vel, growth, angle and spin.

CODE EXAMPLE:

MagicRender.objectspace(
        Global.getSettings().getSprite("fx",zapSprite+chooser),
        ship,
        new Vector2f(point),
        vel,
        new Vector2f(36*rand,36*rand),
        new Vector2f((float)Math.random()*20,(float)Math.random()*20),
        (float)Math.random()*360,
        (float)(Math.random()-0.5f)*10,
        false,
        new Color(255,175,255),
        true,
        0,
        0.2f+(float)Math.random()*0.5f,
        0.2f,
        false
        );

Draws random "zap" sprites around a ship moving towards the back, without fadein, a random duration and a fadeout.
MagicRender code

(boolean) MagicRender.screenCheck (float distance, Vector2f point)

Checks if a point is within a certain distance of the screen's edges.

It is used to avoid spawning particles, especially large amount of them at once, or other effects that won't be seen by the player while impacting performances. Obviously the longer lived the effect is, the farther should be the cut-off distance. The distance is expressed in "screen", so that it is independent of zoom levels. A good default distance is 0.5f, or half a screen away from the edge, but it can be shorter for short lived particles and such.

The game's API does provide a method for the same purpose that checks for the exact distance in SU from the edges of the screen:

(boolean) Global.getCombatEngine().getViewport().isNearViewport(Vector2f location, float distance)

This method is more precise but not zoom-agnostic.

MagicTargetingEdit

Allows "smart" target selection for systems and missiles within distance and search cone parameters, plus it can use ship-class preferences.

(ShipAPI) MagicTargeting.pickTarget(
 CombatEntityAPI seeker,
 targetSeeking seeks,
 Integer maxRange,
 Integer searchCone,
 Integer fighterWeight,
 Integer frigateWeight,
 Integer destroyerWeight,
 Integer cruiserWeight,
 Integer capitalWeight,
 boolean failsafe
)

This script selects a suitable ShipAPI target for either a ship or a missile.

The possible seeking modes are:

NO_RANDOM:     

  • If the ship/source has a valid target, the script will pick it.    
  • If there is no target, the script will check for an unselected cursor target.    
  • If there is none, the script will pick the closest valid threat within the search zone.    

Note that if the seeking entity is a missile, the script will also check for an auto-fire target selected by their weapon group.

LOCAL_RANDOM:

  • If the ship/source has a selected target, the script will pick a random valid threat around that selected target.
  • If there are none, the script will pick a random valid threat around the cursor.
  • If there are none, the script will pick a random valid threat around the ship/missile.

Warning: this behavior can produce strange results if used with a limited search cone.

FULL_RANDOM:

  • The script will always pick a random valid threat around the ship/missile.

IGNORE_SOURCE:

  • The script will pick the closest target of interest. Useful for MIRVs.

CODE EXAMPLE:

(ShipAPI) target = MagicTargeting.pickTarget(
        missile,
        MagicTargeting.targetSeeking..NO_RANDOM,
        (int)missile.getWeapon().getRange(),
        360,
        0,
        1,
        2,
        4,
        4,
        false
        );

This will first aim for the ship target, if none is selected it will look for a possible cursor target, if none are found it will then aim for the closest cruiser or capital and ignore fighters.

(MissileAPI) MagicTargeting.randomMissile(
 CombatEntityAPI source,
 missilePriority priority,
 Vector2f lookAround,
 float direction,
 Integer searchCone,
 Integer maxRange
)

Unlike the other two, this script is targeting MissileAPI. The possible priorities are:    

RANDOM:

  •      Pure random pick within search zone.    

DAMAGE_PRIORITY:

  •      Picks high damage missiles within the search zone first but still has some randomness.    

HIGHEST_DAMAGE:

  •      Picks the highest damage missile within the search zone.
CODE EXAMPLE:
target = MagicTargeting.randomMissile(
        weapon.getShip(),
        MagicTargeting.missilePriority.DAMAGE_PRIORITY,
        weapon.getLocation(),
        weapon.getCurrAngle(),
        90,
        (int)weapon.getRange()
        );
Selects a random missile within 90 degrees in front of a weapon, with high damage priority.

MagicUI Edit

MagicUI.drawSystemBar(
 ShipAPI ship,
 Color intendedColor,
 float fill,
 float blendTime
)
MagicUI.drawSystemBox(
 ShipAPI ship,
 Color intendedColor,
 float blendTime
)

Draws a small UI charge-bar/tick box next to the normal ship-system for special systems.
> ship: Ship concerned (the element will only be drawn if that ship is the player ship)
> intendedColor: Color of the filling. If null, the filling will be UI-green
> fill: Filling level
> blendTime: time taken to switch between colors, can be 0.

CODE EXAMPLE:

MagicUI.drawSystemBar(
        ship,
        new Color(255,0,0),
        shieldTime/MAX_SHIELD_TIME,
        0
);

Create a bar that fills up as long as the shield is kept online.
MagicLib UI


MagicUI.drawInterfaceStatusBar(
 ShipAPI ship, float fill,
 Color innerColor,
 Color borderColor,
 float secondfill,
 String text,
 int number
)

Draw a third status bar above the Flux and Hull ones on the User Interface. With a text of the left and the number on the right.
> ship: Player ship.
> fill Filling: level of the bar. 0 to 1
> innerColor: Color of the bar. If null, the vanilla green UI color will be used.
> borderColor: Color of the border. If null, the vanilla green UI color will be used.
> secondfill: Wider filling like the soft/hard-flux. 0 to 1.
> text: The text written to the left, automatically cut if too large.
> number: The number displayed on the right. Can go from 0 to 999 999.

Interfacebar



MagicUI.drawHUDStatusBar(
 ShipAPI ship, float fill,
 Color innerColor,
 Color borderColor,
 float secondfill,
String bottext,
String toptext,
boolean offset
)

Draw a status bar next to the player ship on the top left corner of the hud. Can write two bits of text on its left side.
> bottext: Write a text just on the left of the bar. Example: 'flux'
> toptext: Write a text just above the bar. Example: 'player' or 'target'
> Offsets: the bar a few pixels upward. Can be used for example to display the targeted enemy special status bar.

Screenshot668





MagicMissileAI Edit

A very customizable and lightweight missile AI script usable without any java knowledge. All the actionable parameters are fully commented within the script.

MagicVectorThrusterEdit

Manages vectoring or vernier-style attitude thrusters.

"everyFrameEffect":"data.scripts.weapons.MagicVectorThruster",   

Just needs to be assigned to a deco weapon with a "flame" animation or a "cover" sprite in their weapon file. Supports both moving vectoring-style thrusters and fixed vernier-style ones.


vectoring-style thruster example image

MagicVectorThruster fixedVernierExample
WARNING, this script may have a negative performances impact, use it sparingly.

MagicTrailPlugin Edit

Allows custom QUAD_STRIP-style trails to be drawn freely, with a bunch of customization available. The trails are made by spawning "trail pieces", which if they have the same ID links together to form a smooth trail (the trail will not render without having at least 2 pieces link together).

These are the main functions included in MagicTrailPlugin

MagicTrailPlugin.AddTrailMemberSimple(CombatEntityAPI linkedEntity, float ID, SpriteAPI sprite, Vector2f position, float speed, float angle, float startSize, float endSize, Color color, float opacity, float duration, boolean additive, Vector2f offsetVelocity)

Spawns a trail piece, which links up with other pieces with the same ID to form a smooth trail. This function has most of the functionality you need; should you want more configurability, use AddTrailMemberAdvanced instead.

Parameters: Edit

linkedEntity : The entity this trail is attached to (this is used for cutting trails). Can be null to make a trail un-cuttable, but this should generally never be done

ID : The ID for this specific trail, any other trail pieces with the same ID links up to form a trail. This should preferably be gotten from MagicTrailPlugin.getUniqueID().

sprite : Which sprite to use when drawing this trail. Do not change this mid-trail; make another trail instead or use MagicTrailPlugin.AddTrailMemberAnimated() (see below).

position : Starting position for this piece of trail.

speed : The trail piece's speed, in SU/s.

angle : The angle the trail piece has when spawned, in degrees. This determines both it travel direction and which direction its width is calculated across.

startAngularVelocity : The angular velocity this trail piece has when spawned. The actual angular velocity will go from startAngularVelocity to endAngularVelocity over the trail's lifetime.

endAngularVelocity : See "startAngularVelocity" above.

startSize : The starting width of a trail piece (measured in SU). The actual width will go from startSize to endSize over the trail's life.

endSize : See "startSize" above.

color : The color of this piece of trail. Can be changed mid-trail, and will smoothly blend between trail pieces.

opacity : The starting opacity of this trail (defined between 1f and 0f); the trail's actual opacity will go from this value to 0f over its lifetime.

duration : How long the trail piece lasts, in seconds

additive : Whether the trail uses additive blending or not. Can not be changed mid-trail.

offsetVelocity : The offset velocity of the trail; this is an additional velocity that is unaffected by rotation and facing, and will never change over the trail's lifetime.

MagicTrailPlugin.AddTrailMemberAdvanced(CombatEntityAPI linkedEntity, float ID, SpriteAPI sprite, Vector2f position, float startSpeed, float endSpeed, float angle, float startAngularVelocity, float endAngularVelocity, float startSize, float endSize, Color startColor, Color endColor, float opacity, float inDuration, float mainDuration, float outDuration, int blendModeSRC, int blendModeDEST, float textureLoopLength, float textureScrollSpeed, Vector2f offsetVelocity, float aggressiveCulling, @Nullable Map<String,Object> advancedOptions)

Spawns a trail piece, which links up with other pieces with the same ID to form a smooth trail. This function has all available functions; if you just want to spawn a normal trail without all the extra configuration involved, use AddTrailMemberSimple instead.

Parameters: Edit

linkedEntity : The entity this trail is attached to (this is used for cutting trails). Can be null to make a trail un-cuttable, but this should generally never be done

ID : The ID for this specific trail, any other trail pieces with the same ID links up to form a trail. This should preferably be gotten from MagicTrailPlugin.getUniqueID().

sprite : Which sprite to use when drawing this trail. Do not change this mid-trail; make another trail instead or use MagicTrailPlugin.AddTrailMemberAnimated() (see below).

position : Starting position for this piece of trail.

startSpeed : The trail piece's starting speed. The actual speed will gradually go from startSpeed to endSpeed over the trail piece's lifetime.

endSpeed : See "startSpeed" above.

angle : The angle the trail piece has when spawned, in degrees. This determines both it travel direction and which direction its width is calculated across.

startAngularVelocity : The angular velocity this trail piece has when spawned. The actual angular velocity will go from startAngularVelocity to endAngularVelocity over the trail's lifetime.

endAngularVelocity : See "startAngularVelocity" above.

startSize : The starting width of a trail piece (measured in SU). The actual width will go from startSize to endSize over the trail's life.

endSize : See "startSize" above.

---PAGE WIP: MORE STUFF WILL BE ADDED---

MagicTrailPlugin.AddTrailMemberAnimated(CombatEntityAPI linkedEntity, float ID, SpriteAPI sprite, Vector2f position, float startSpeed, float endSpeed, float angle, float startAngularVelocity, float endAngularVelocity, float startSize, float endSize, Color startColor, Color endColor, float opacity, float inDuration, float mainDuration, float outDuration, int blendModeSRC, int blendModeDEST, float textureLoopLength, float textureScrollSpeed, Vector2f offsetVelocity, float aggressiveCulling, @Nullable Map<String,Object> advancedOptions)

Spawns a trail piece, which links up with other pieces with the same ID to form a smooth trail. This function is identical to the Advanced function, but allows the trail to change its texture each time a new member is added. It will always use the texture of the most recently-added member. If the texture is not supposed to be animated, do NOT use this function: it runs notably slower.

Parameters: Edit

Same as AddTrailAdvanced, except for:

sprite : The sprite for the trail; if this is changed mid-trail, the entire trail changes sprite to the newest-added sprite.

MagicTrailPlugin.getUniqueID()

Gets a unique Float ID for the purpose of generating trails. Should ideally not be used for non-trail IDs since it is very simplistic.

MagicTrailPlugin.cutTrailsOnEntity(CombatEntityAPI entity)

"Cuts" all trails on a designated entity, forcing new trail pieces to not link up with old ones. Should be used before teleporting any entity, since it may have trails attached to it which will otherwise stretch in unintended ways.

This can also be called (with a potential 1-frame delay) by adding an entity to any CustomData in the CombatEngineAPI with a key containing the phrase "MagicTrailPlugin_LIB_FREE_TRAIL_CUT" (note: *containing*; there must be more to the key than this, as it should be unique [optimally, add your modID and the ID of the ship trying to cut the trails]). This alternate  calling method does not require MagicLib, and may thus be optimal for smaller mods or mods that don't want any  other MagicLib features but still needs trail-cutting support

Parameters: Edit

entity : The entity you want to cut all trails on. Cannot be null.

Icon check temp
Only up to date for version 0.8.1a-RC8. It is likely still broadly correct but not verified for the most up to date data yet. Please double check the Version History



Return to: Modding

Community content is available under CC-BY-SA unless otherwise noted.