Custom Modules Thread

[planetfall]

This thread is for people to share scripts, images, techniques and what-have-you related to custom modules. The first post is a brief overview of how to create custom modules and include them in your maps - using the scripts I developed during the beta. If these give you rubbish performance or lack a feature you'd like, I encourage you to try and find a better way!

Please note: the scripts in this thread may be updated, which may break something if you use them without understanding the changes and updating your own scripts accordingly. Virgil has stated that official support for custom modules will come at some point. There is no guarantee that any custom modules created on this system will work with whatever format Virgil comes up with - so in the long term this work may be wasted unless you had fun doing it.

Custom modules are no longer planned, but there may be some future updates that render some of the framework obsolete.

The first script you'll need is ShipModule.prpl (attached), which will work for you OOTB. It should NOT be attached to any cores at the start of the map, however this script will end up attached to all custom modules and performs basic actions: moving with the ship, building, getting destroyed when the hull it's on is lost, etc. It doesn't do anything more advanced like fire at particles - that has to come from your own module script. More on that below.

Designing your ship

The second script you will need for sure is one to apply custom modules to ship blueprints. In my maps I call it Master.prpl. First just go and create a ship with some blank spots on it for your modules to fit in. Custom modules can be any size but they must be rectangular. Someone with a better aesthetic sense than myself can talk about how to design cool ships. :)

Then, create a script somewhat like the following one. This will go on an invisible core off the map somewhere.

Code Select Expand


24 0 do
I GetShipNameFromSlot ->ShipName
<-ShipName "BlueprintName" eq if
I GetShipFromSlot ->uid
<-uid.ShipIsDestroyed eq0 if
<-uid <-! eq0 if
1 <-uid ->!
...
endif
endif
endif

<-ShipName "AnotherBlueprintName" eq if
I GetShipFromSlot ->uid
<-uid.ShipIsDestroyed eq0 if
<-uid <-! eq0 if
1 <-uid ->!
...
endif
endif
endif


loop


The ... is what we're interested in - this is where we spawn the modules. You'll also have to put in the name of your ship where it says BlueprintName. To add one module to a ship looks somewhat like this:

Code Select Expand


"PRPLCORE" 0 0 CreateUnit ->module
<-module "ShipModule.prpl" AddScriptToUnit
<-module "ShipModule.prpl" "width" 3 SetScriptVar
<-module "ShipModule.prpl" "height" 3 SetScriptVar
<-module "ShipModule.prpl" "hullX" 1 SetScriptVar
<-module "ShipModule.prpl" "hullY" 1 SetScriptVar
<-module "ShipModule.prpl" "CommandX" 4 SetScriptVar
<-module "ShipModule.prpl" "CommandY" 5 SetScriptVar
<-module "ShipModule.prpl" "BuildCost" 80 SetScriptVar
<-module "ShipModule.prpl" "Ship" <-uid SetScriptVar
<-module "Maker.prpl" AddScriptToUnit


All of these parameters should be more or less self-explanatory. A note though: the hullX and hullY refer to the lower left cell occupied by the module, while CommandX and CommandY  refer to the center of the bridge. Ship hull coordinates start at 0,0 in the bottom left - of the hull, not of the ship design window. So if you change your design to be wider or taller, you may need to modify your script as the coordinates will have changed.



If you want to share a ship file meant to be used with custom modules, it lies somewhere on the spectrum between "common courtesy" and "absolutely imperative" that you provide the PRPL to spawn the modules at the correct locations (not to mention a copy of, or link to, the script specifying the module's functionality.)

Which leads me to the next topic...

The above method works only for ships in the player's inventory. If you want it to work for ships from spawners, you must use a script similar to ShipSpawnerManager from the exchange map "Mutually Assured."

How to Program your Module

Far be it from me to dictate what kinds of things you create in PRPL. This will only explain how to create modules that roughly emulate the builtin modules - if for some reason you want a module that only operates when the hull it's on isn't built, guess you'll have to look at the scripts.

This is a rough template.

Code Select Expand


once
# Set up image(s). You NEED to set image layer to Ships, otherwise your module will render behind ships.
Self "main" "CustomSomething" SetImage
Self "main" "Ships" SetImageLayer
Self "main" 1 SetImageOrder
Self "main" 1 1 SetImageScale
Self "ShipModule.prpl" "Ship" GetScriptVar ->Ship
<-Ship.ShipIsEnemy ->IsEnemy
-1 ->target
endonce

#The heading of the ship the module is attached to.
Self "ShipModule.prpl" "ShipAngle" GetScriptVar ->ShipAngle

#The amount the heading has changed in the last frame (in radians)
Self "ShipModule.prpl" "delta" GetScriptVar ->Delta

#Whether the module exists.
#0 = hull destroyed
#1 = under construction
#2 = built
Self "ShipModule.prpl" "exist" GetScriptVar ->Exist

#If the module is destroyed, make it invisible and prevent the rest of the script from running.
<-Exist eq0 if
self "main" 0 0 0 0 SetImageColor
return
endif

#make module align with ship
self "main" <-ShipAngle SetImageRotation

IsPaused if
return
endif

<-Exist 1 eq if
# if under construction, make the module semi transparent.
# also use this for things like resetting turret rotation or cooldown if the module is destroyed and rebuilt
self "main" 255 255 255 128 SetImageColor
else
self "main" 255 255 255 255 SetImageColor
# I don't know of a way to read the Fire Multiple property on some enemy ships, which increases their fire rate.
# Instead, this script pretends that all enemy ships have amp gems.
<-Ship.ShipHasAmp <-IsEnemy or ->GemPresent
#code your module's abilities here
endif

:awake
# I dunno, I like to have all my scrpts OWP and exit partway through, I doubt it's caused by the brain chip.
1 OperateWhilePaused


[planetfall]

Custom Module: Decoupler

Spoiler

Fires a beam at bonded particles and breaks all bonds in the formation. Useful vs. doppels, as the core is exposed for a short time.
Requires time for the barrel to rotate.
If unit uids are stored in a global list variable called DecouplerTargets, it will prioritize them over particles and destroy them in one hit.
Amp effect: 2x fire rate, 1.2x range

Note: This script requires BeamEffect.prpl for the fading beam.

[close]

Custom Module: Sniper

Spoiler

Deals 8 damage to particles with slow fire rate. Higher DPS than cannons or missiles, but inflicts no knockback. Targets heaviest particle in range, ignores particles with <3 health.
If unit uids are stored in a global list variable called SniperTargets, it will prioritize them over particles and deal 8 damage.
I've also tried to make them able to target Emergent - no luck.
Amp effect: 2x fiire rate, 1.2x range

Note: This script requires BeamEffect.prpl for the fading beam.

[close]

Custom Module: Nuker

Spoiler

Fires a powerful missile at certain targets: energy mines, ships, doppels, omnis (if enemy owned), emitters. Emitters can't be destroyed by this weapon but it helps with clearing out particles. It also leaves an exhaust trail of short-lived particles that distract enemy weapons.
The missile's core is a high-health particle that can be destroyed with snipers. The missile script drives the particle and the particle simulation drives the missile. Thus, the missile's interaction with land depends on the "particles over mired land" setting.
Amp effect: 1.5x fire rate, 1.2x range

Note: This script requires Nuke.prpl for the projectile itself.

[close]

Custom Module: Sprayer

Spoiler

Takes in concentrated particles behind it and spreads them out in front.
Amp effect: none

[close]

Custom Module: Booster

Spoiler

Increases nearby friendly particles' max speed. If they have a limited lifespan, also raises that. Useful for extending the range of blue particle chains.
The version attached to this thread is buffed from the one found in Daisy Chain, which is more or less useless.
Default: affects all particles in a radius of 5, increases max speed to 0.9, increases lifespan by 6 frames each frame
Amp: affects all particles in a radius of 7, increases max speed to 1.05, increases lifespan by 11 frames each frame

(The one in Daisy Chain uses the nuker1 image.)

[close]

Custom Module: Maker

Spoiler

Converts energy to particles.
Default: particles have 1 health, 60 second lifespan, 250 particles max
Amp: particles have 2 health, 90 second lifespan, 500 particles max

[close]

Scripts and images are attached. Images are not attached for those which use unmodified CW3 assets for their images (in the name of not wasting precious server space.)

[planetfall]

reserved in the name of optimism

[GoodMorning]

As of this post, Virgil will be allowing for integrated custom modules, with some UI integration, at some point.

Edit: Full custom modules are no longer planned.

As at V1.02:
GetShipEnergy and SetShipEnergy can now change ship energy levels. [GS]etShipEnergyCap will compile, but appears to default to -1, with a positive value being a hard limit on contained energy, though the ship will still request packets. You can read but not set ShipCMCost, and you can set the ship CM built amt. The ship appears to need to receive a packet in order to complete building. Setting ship energy to negatives can have strange effects.

[3301]

I made a map with all of those prpl modules:
https://www.dropbox.com/sh/03qi9d46y5bw8no/AACpfmr5nWNFjMdpS68waQRga?dl=0

(stick the save.pf1 in a folder named anything in \Documents\My Games\particlefleet\editor\)

[planetfall]

Update Dec 15 2016:

Updated ShipModule.prpl, Sniper.prpl, Decoupler.prpl, Nuker.prpl and Maker.prpl, above. Now use GetShipEnergy/SetShipEnergy instead of drawing from global storage.
Enemy ships no longer get to use these modules for free.
Nuker no longer has that weird 10-energy cost when firing that doesn't prevent it from firing if not provided. (Honestly! What was I thinking?!)

[Nicant]

Here is my module that i have been working on the past few days. There is still a few things to do with it, but it is functional the way it is. Attached is the script and images for the module. Do note: This module also requires BeamEffect and GreyBeam. You can get those above.

The module's function is to find any enemy stunner is a 35 range. If there happens to be a stunner in its range, it will "convert" that stunner into a friendly stunner. The friendly stunner will then go after an enemy ship. This module is not recommended for maps that do not have any enemy ships in them.

Edit: Here is another module i have made! It is called a micro engine and it is basically a normal engine module, but it is smaller and can be used for small ships where there is not enough room for a regular engine. Provided is the image, (Image is 128x128 sized) a picture of the module on a ship, and the script! Do note one downside of this module is that the rotate speed is not affected so if you only use the micro-engine and no normal engines, the rotate speed will be slow.

[3301]

Will maker, booster, and sprayer work on enemy ships? I got nuker, sniper and decoupler modules on enemy ships but the other 3 don't.

[3301]

Nevermind it works.

[tornado]

I'm working on my own custom module.
its slow going, has been done before, and i have no understanding of PRPL at all.
Still, every jedi must build their own lightsaber and all.
Might look at how you're doing the targeting on snipers and so on(because being able to say "shoot this first!" seems like a good thing to have.

[Qihao56]

Hey planetfall can I get some help on making a custom airstrip for better fighters and torpedo bombers(specialized anti-ship plane)

[tornado]

Edit: Here is another module i have made! It is called a micro engine and it is basically a normal engine module, but it is smaller and can be used for small ships where there is not enough room for a regular engine. Provided is the image, (Image is 128x128 sized) a picture of the module on a ship, and the script! Do note one downside of this module is that the rotate speed is not affected so if you only use the micro-engine and no normal engines, the rotate speed will be slow.

Given my tendency to create minute ships this will be, practical.

[Eiyatizu]

Adapted from JoaoPistori's Map 506 and came up with the following weapons.

GeassWeapon: Convert enemy units by setting enemy status and creating particles at enemy CM to kill it instantly (Lelouch's instant kill command).

SuperlaserWeapon: Damage enemy units and ships...

Kamehameha: A particle beam, constantly generated and moving forward at a base speed plus ship's speed to maintain the beam's consistency.

Shield Module: A particle shield, all particles tracked to force their movement to certain positions along with the module.

[tornado]

Hey, quick question. I'm trying to use the sniper module on one of my ships, but I cant seem to find the image for it(there's the greybeam image but not the module image).

[Nicant]

Hey, quick question. I'm trying to use the sniper module on one of my ships, but I cant seem to find the image for it(there's the greybeam image but not the module image).

You get the sniper image from the wiki. http://knucklecracker.com/wiki/doku.php?id=crpl:custom_image_repository It is not shown because it saves some server space.