Cocos plugin tutorial: Experience sharing on writing plugins with extended attributes

I wrote a 2D particle control using a cocos plugin these days. It's obvious that the official documentation is not very complete, and the super long description is not very clear, so I fell into many traps and took many detours during this period. However, the plugin system released by cocos this time is still very flexible and powerful, and we can customize everything from editing to final output. This tutorial will share my experience in the process of extending attributes in the past two days, and explore some techniques in the process of plugin writing to help those who come later.

1. How to get started?

Maybe you have read this "Cocos Studio Extension Instructions" (hereinafter referred to as "Instructions") before:

http://cn.cocos2d-x.org/tutorial/show?id=2650

This shows that the length of the article is so long that it probably scared off many people. Those who mustered up the courage to read it probably fell asleep halfway through. (I fell asleep a few times while reading it. The amount of information is really too much. Is there a hypnotic tool...)

The actual plug-in writing is not that complicated. You can directly modify the sample project provided by the official.

Open the sample project. (For the path of the sample project, please refer to point 3 "Sample Project Location" in the Instructions)

You can see that there are so many files in it:

illustrate:

ü DataModel, Templates and ViewModel are examples of an official Custom control. There are also three similar folders under the Lua folder. This is the source code of the text sprite plug-in.

ü Editor is an example of a custom control in the property area.

ü PublishExtend is an example of customizing the export data format.

ü AddinConfig is the configuration file of the plug-in, which configures the modules that the current plug-in depends on. We do not need to change it at present.

Copy the plugin project, keep the example we want to use as a template, and delete other files.

I hope to write a particle plug-in without customizing the Editor and exporting data formats, so I only keep the ExtensionModel and Lua folders and rename "Lua" to "Particle", as shown below:

Then make some modifications to the remaining files according to our needs:

1. LuaObject.addin.xml file

Modify the class generated for the T4 template.

2. CustomParticleObject.cs file under ViewModel

This file needs to be modified in three places

a. These four properties are mainly used to display some information of the control in the editor. The type inherited by CustomParticleObject also needs to be modified according to your needs. (See the "View Model" section in the "Instructions" for details)

b. The default name when creating the plugin.

c. Dependent Lua files. That is, the Lua files corresponding to this plug-in in the LuaScript folder.

3. Modify the following two places in CustomParticleObjectData.cs of DataModel:

4. In the CustomParticleObject.tt template file in the Lua folder, modify the inherited object type and the class name of the ViewModel class. (For details, see the "Lua Code Generation Template" section of the "Instructions")

OK, after changing these, we have configured a plug-in project. Next, we need to complete the engine expansion in Lua, and then call the Lua interface in the editor.

PS: After upgrading from 2.2.1 to 2.2.5, you need to upgrade the plug-in project accordingly. For details, please refer to Addins/Addins.Sample/Lua/Modification Record.txt in the new version sample project.

2. Write the corresponding Lua file

This step is mainly to prepare our interface and call it for the C# project configured above.

First, there are four things you must do:

1. Return a table to the plugin project at the end of the file, and the plugin project will then look for the required interface in this table. Here we call this table "container"

2. Add the CreateCustomNode factory function for "container", create a Cocos2d-x object we extended and return it.

3. Add a GetBaseType function to "container" to return the base type of our plugin. (Later, our plugin will also have an editing interface for this base type.)

4. Put the written file in Addins/LuaScript of cocos document path

Then add some attribute interfaces to the table described in 1 to exchange data with the plug-in project. The exchangeable data can only be the following data types, and only one data can be exchanged at a time:

Bool

Int

String

Double

Float

Color

ResourceData

PS: Lua does not distinguish between Float, Double and Int, all of them are carried by double.

Skill:

1. The plugin project does not use the rawget method to search for fields on the table, so the metatable is still available. We can set the __index metatable for the table and redirect it to our extended 2d-x object. Some of the simple interfaces of the objects we extend can be located using the metatable, so there is no need to write them again in the table, which reduces the workload.

2. If there is an error in this lua file, cocos will not give any useful debugging information. We can debug it in a 2d-lua project first, and then put it into cocos after all interfaces work normally, which can save a lot of time.

3. This file may not be related to the final exported data.

3. Add an interface to exchange data with the Lua layer in the plug-in project

The main thing is to write some properties for the view model (the object in the ViewModel folder). Each time a property editor is written, a property control will be generated in the property area. Then you can use these property controls for visual editing.

Communication with Lua requires calling the Lua layer interface through LuaValueConverter to exchange data.

A basic property looks like this:

[UndoPropertyAttribute]

[DisplayName("TangentialAccel")]

[Category("Group_Feature")]

[PropertyOrder(-99)]

[Browsable(true)]

public float TangentialAccel

{

get

{

return luaValueConverter.GetFloatValue("getTangentialAccel");

}

set

{

luaValueConverter.SetFloatValue("setTangentialAccel",value);

this.RaisePropertyChanged(() => this.TangentialAccel);

}

}

First, there are several attributes enclosed in square brackets, declarations of the current property, and then getter and setter definitions. The role of attribute values ​​can be found in the "Attribute Area Extension" section of the "Instructions".

Secondly, there is the setValue function. This function is used when performing a cloning operation. It assigns the property written above to the corresponding property of the passed in cObject object.

Skill:

1. If there are many attributes, you can first write the same type of extended attributes, debug them until they are usable, then copy and paste them and modify the name.

2. You can use Cocos Studio.Basic.LogConfig.Output.Info(String) to output error information in the C# plug-in project.

3. When debugging, use VS's "Debug" - "Attach to Process" to attach to the Cocos Studio main process for debugging. When an error occurs in the C# code, VS will help you point out the error location and provide detailed debugging information. All errors that cause crashes can generally be located.

4. Currently, there is no interface for outputting error information in Lua. A small amount of debugging information can be output by placing a text control on the created node. The socket and io modules in Lua can still be used. We can use these two modules to output debugging information. I use socket. You can refer to my source code. The developers of cocos said that they will provide a log interface as soon as possible, so it will not be so troublesome.

4. Edit DataModel

That is, in the CustomParticleObjectData.cs file, declare the properties that need to be saved to the csd file in the form of properties, with [ItemProperty] [JsonProperty] in front. In this way, the data will be saved in the csd file. When we close the editor and open it again, the edited data will not be lost. When generating a T4 template, the values ​​referenced in the template also come from here.

Note that the properties of the color type must be declared using ColorData (yes, I have been fooled before). The possible error here is that the data type is written incorrectly, and the phenomenon is that it cannot be saved or exported.

5. Code Generation Template

That is, the CustomParticleObject.tt template file in the Lua folder. Its function is to output the value edited by the editor according to a specific template.

Skill:

If you look at my lua file and T4 template, you will find that there is no connection between the two. CreateCustomNode in my lua file creates a node object and then creates a particle object as a child object of the node. The purpose of this is to achieve the effect of changing the particle template (changing the particle template requires regenerating the particle object).

In fact, T4 fills the value into the string according to the template and finally saves it to the file. If you want, it can generate C++ code.