2DFX Effects API

[FileEX]

This PR adds the ability to add, remove, and edit 2DFX effects. It's also possible to edit and remove 2DFX effects from existing objects without the need to edit the model.

Available effect types (relevant in MTA):

• LIGHT
• PARTICLE
• SUN_GLARE
• ROADSIGN
• ESCALATOR

Note: The escalator effect allows for the creation of moving escalators

Elements that supports 2dfx with this PR

• Objects
• Buildings
• Vehicles

This PR is still under development. I have a few more ideas on how I want to expand and simplify it. As for limitations, the limit is the same as with normal model editing, meaning as much as your memory can handle.

Available functions:

2dfx addModel2DFX(int modelID, float x, float y, float z, string effectType, table effectProperties)
bool removeModel2DFX(int modelID [, int index, bool includeDefault = false ] )
bool setModel2DFXProperties(int modelID, int index, table effectProperties)
bool set2DFXProperties(2dfx effect, table effectProperties)
bool setModel2DFXProperty(int modelID, int index, string property, mix value)
mix getModel2DFXProperty(int modelID, int index, string property)
bool set2DFXProperty(2dfx effect, string property, mix value)
mix get2DFXProperty(2dfx effect, string property)
bool setModel2DFXPosition(int modelID, int index, float x, float y, float z)
bool set2DFXPosition(2dfx effect, float x, float y, float z)
float, float, float getModel2DFXPosition(int modelID, int index)
table getModel2DFXProperties(int modelID, int index)
table get2DFXProperties(2dfx effect)
int getModel2DFXCount(int modelID)
bool resetModel2DFX(int modelID [, bool removeCustomEffects = true ] )

Functions that have the word 'model' in their name are intended for existing default world objects, while those without this prefix are meant for custom effects created using engineAddModel2DFX.

Examples

local fire = addModel2DFX(1337, 0.1, 0.1, 0.8, 'particle', {name='fire'});

local effect = addModel2DFX(1337, 0.1, 0.1, 0.75, 'light', {
	drawDistance = 100,
	lightRange = 18,
	coronaSize = 2,
	shadowSize = 10,
	shadowMultiplier = 40,
	showMode = "default",
	coronaReflection = false,
	flareType = 0,
	flags = 96,
	shadowDistance = 0,
	offsetX = 0,
	offsetY = 0,
	offsetZ = 0,
	color = tocolor(50, 168, 82, 255),
	coronaName = "coronamoon",
	shadowName = "shad_exp",
})

removeModel2DFX(3524, 0, true)

A detailed description along with documentation will be added when the PR is 100% complete and ready for review. Most of the work has already been done, here's a short to-do list:

- Removing custom effects via destroyElement

• Tests, tests, and more tests...
• Possible cleanup (at the very end)

Possibly resolves: #3579

[FileEX]

Update

• Added 4 new functions:

bool setModel2DFXProperty(int modelID, int index, string property, mix value)
mix getModel2DFXProperty(int modelID, int index, string property)
bool set2DFXProperty(2dfx effect, string property, mix value)
mix get2DFXProperty(2dfx effect, string property)

• Added effect removal with destroyElement
• Little cleanup

But PR is still a work in progress.

[Meine1]

what about a property for setting 2DFX dimension/interior ? also isn't the corona limit still 64 so something like Project2DFX's LOD lights still wouldn't be possible?

[FileEX]

what about a property for setting 2DFX dimension/interior ?

2DFX effects do not have their own dimension and interior. They are part of the model, so they take on the same dimension and interior as the given object/building.

also isn't the corona limit still 64 so something like Project2DFX's LOD lights still wouldn't be possible?

The current limit for visible coronas is indeed 64. I already know where and what needs to be done to increase it. However, I'm wondering whether it should be done as part of this PR or as a separate feature like a 'limit adjuster'

[ds1-e]

Is it possible to apply effect to certain MTA object, just like targetElement when applying shader?

[TheNormalnij]

Can you create a new 2DFX class for this instead of using engine class defs?

[Meine1]

I already know where and what needs to be done to increase it. However, I'm wondering whether it should be done as part of this PR or as a separate feature like a 'limit adjuster'

if the corona limit fix is not too complex, it would be a good idea to make it part of this because a full limit adjuster with more features would be another whole beast.

[FileEX]

Is it possible to apply effect to certain MTA object, just like targetElement when applying shader?

If I'm not mistaken, each entity has its own RwObject, so it should be possible to add an effect only for one object, and not for all with this id