How To Create Plugins: Difference between revisions

From Resonite Wiki
m fix link
Basic Types -> add ExternalDataModelType
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
<languages />
{{Technical}}
{{Technical}}
Plugins are used to add more [[Component|Components]] and [[ProtoFlux]] nodes to Resonite by programming them using C#. They are not to be confused with [[Mods]] which do not add things into the [[Data_Model#Mods_VS_Plugins|Data Model]].
<translate>Plugins are used to add more [[Component|Components]] and [[ProtoFlux]] nodes to Resonite by programming them using C#. They are not to be confused with [[Mods]] which do not add things into the [[Data_Model#Mods_VS_Plugins|Data Model]].</translate>


: ''This page is about '''writing plugins''' and should not be confused with the [[Plugins|Plugin overview]] page.''
: ''<translate>This page is about '''writing plugins''' and should not be confused with the [[Plugins|Plugin overview]] page.</translate>''


Please see [[Plugins#Plugin_Guidelines|the plugin guidelines]] before getting started, to familiarize yourself on what is and is not allowed.
<translate>Please see [[Plugins#Plugin_Guidelines|the plugin guidelines]] before getting started, to familiarize yourself on what is and is not allowed.</translate>


== Getting started ==
== <translate>Getting started</translate> ==
''You will need to know the basics of the [https://learn.microsoft.com/en-us/dotnet/csharp/ C# Programming Language] to write plugins.''
''<translate>You will need to know the basics of the [https://learn.microsoft.com/en-us/dotnet/csharp/ C# Programming Language] to write plugins.</translate>''


# Download [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community edition], which allows for easier programming and compilation of plugins. ''However, you can use your favourite code editor as long as you know how to compile C# into a <code>.dll</code>''
# <translate>Download [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community edition], which allows for easier programming and compilation of plugins.</translate> ''<translate>However, you can use your favourite code editor as long as you know how to compile C# into a</translate> <code>.dll</code>''
#* During installation, ensure to select .NET desktop development which will give you the .NET Framework development tools, which are required to compile a plugin
#* <translate>During installation, ensure to select .NET desktop development which will give you the .NET Framework development tools, which are required to compile the plugin</translate>
# Create a new project using the <code>Class Library</code> template (please ensure it is the C# option). Guidelines follow:
# <translate>Create a new project using the <code>Class Library</code> template (please ensure it is the C# option). Guidelines follow:</translate>
## The project name ''should'' be the name of your plugin, same with the ''solution name''. It is recommended to not check the box for ''Place solution and project in the same directory'', as you may have multiple parts to your plugin, such as a [[How_To_Write_Plugins/ProtoFlux_Binding|ProtoFlux Binding]] generator.
## <translate>The project name ''should'' be the name of your plugin, same with the ''solution name''. It is recommended to '''not''' check the box for ''Place solution and project in the same directory'', as you may have multiple parts to your plugin, such as a [[How_To_Create_Plugins/ProtoFlux_Binding|ProtoFlux Binding]] generator.</translate>
## Select the default framework, we'll be manually editing this later.
## <translate>Select the default framework, we'll be manually editing this later.</translate>
# Add references to the following libraries by right clicking on <code>Dependencies</code>, clicking <code>Add Project Reference</code> and then <code>Browse</code>.
# <translate>Add references to the following libraries by right clicking on <code>Dependencies</code>, clicking <code>Add Project Reference</code> and then <code>Browse</code>.</translate>
## FrooxEngine.dll - Found in Resonite/Resonite_Data/Managed/FrooxEngine.dll
## FrooxEngine.dll - <translate>Found in</translate> Resonite/Resonite_Data/Managed/FrooxEngine.dll
## Elements.Core.dll - Found in Resonite/Resonite_Data/Managed/Elements.Core.dll
## Elements.Core.dll - <translate>Found in</translate> Resonite/Resonite_Data/Managed/Elements.Core.dll
# Change the referenced framework to <code>net48</code>. To do this:
# <translate>Change the referenced framework to</translate> <code>net462</code>. <translate>To do this:</translate>
## Double click on your namespace, this will be under your solution
## <translate>Double click on your project name, this will be under your solution</translate>
## Change the line <code><nowiki><TargetFramework>whatever_you_selected_earlier</TargetFramework></nowiki></code> to <code><nowiki><TargetFramework>net462</TargetFramework></nowiki></code> and saving the file
## <translate>Change the line</translate> <code><TargetFramework><translate>whatever_you_selected_earlier</translate></TargetFramework></code> <translate>to</translate> <code><nowiki><TargetFramework>net462</TargetFramework></nowiki></code> <translate>and save the file</translate>
# Change Your Assembly Info file to tell [[FrooxEngine]] what type of plugin you are making.
# <translate>Change Your Assembly Info file to tell [[FrooxEngine]] what type of plugin you are making.</translate>
## You will need to add the following line into your Project properties file:<br><code><GenerateAssemblyInfo>false</GenerateAssemblyInfo></code><br>inside of a <code>PropertyGroup</code>
## <translate>Create a folder inside your project called</translate> <code>Properties</code>
## Create a folder inside your project called <code>Properties</code>
## <translate>Create a file called</translate> <code>AssemblyInfo.cs</code> <translate>which contains the line</translate> <code><nowiki>[assembly: DataModelAssembly(t)]</nowiki></code><translate>, where</translate> <code>t</code> <translate>is a [[How_To_Create_Plugins/DataModelAssemblyType|DataModelAssemblyType]].</translate>
## Create a file called <code>AssemblyInfo.cs</code> which contains the line <code><nowiki>[assembly: DataModelAssembly(t)]</nowiki></code>, where <code>t</code> is a [[How_To_Write_Plugins/DataModelAssemblyType|DataModelAssemblyType]].


{{Note|The framework <code>net462</code> (step 4) is going to be changed in the future, this will most likely happen with the switch from Unity to [[Sauce]]|warning}}
{{Note|<translate>The framework</translate> <code>net462</code> <translate>(step 4) is going to be changed in the future, this will most likely happen with the switch from Unity to [[Sauce]]</translate>|warning}}


You're now ready to start writing plugins!
<translate>'''You're now ready to start writing plugins!'''</translate>
Please see the following pages for in depth guides on how to code individual parts of plugins:
== Guides ==
* Creating custom [[How_To_Write_Plugins/Creating_Components|Components]]
=== Components ===
* An introduction to creating custom [[How_To_Write_Plugins/Creating_ProtoFlux_Nodes|ProtoFlux]] nodes
* [[How_To_Create_Plugins/Creating_Components|<translate>Creating custom Components</translate>]]
* Creating a [[How_To_Write_Plugins/Creating_Bindings|ProtoFlux Binding]]
''Please note: you are not limited to these guides, you may use any C# syntax.''


== Object Reference ==
=== ProtoFlux ===
* <translate>An introduction to</translate> [[How_To_Create_Plugins/Creating_ProtoFlux_Nodes|<translate>creating custom ProtoFlux nodes</translate>]]
* <translate>[[How_To_Create_Plugins/ProtoFlux_CC|Calls and Continuations]] in ProtoFlux</translate>
* <translate>[[How_To_Create_Plugins/ProtoFlux_Globals|Creating ProtoFlux Globals]]</translate>
* [[How_To_Create_Plugins/Creating_ProtoFlux_Bindings|<translate>Creating a ProtoFlux Binding</translate>]]
 
=== Misc ===
* <translate>[[How_To_Create_Plugins/Creating_Settings|Creating settings]]</translate>
 
== <translate>Object Reference</translate> ==
{{Under construction|section|Doesn't list all types relevant for writing plugins.}}
=== Basic Types ===
{| class="wikitable sortable"
{| class="wikitable sortable"
|-
|-
! Object
! <translate>Object</translate>
! Description
! <translate>Description</translate>
|-
| [[How_To_Create_Plugins/Custom_Components|Components]]
| <translate>A custom component</translate>
|-
| [[How_To_Create_Plugins/DataModelAssemblyType|DataModelAssemblyType]]
| <translate>The type of assembly you are making. Used in your</translate> <code>AssemblyInfo.cs</code> <translate>file.</translate>
|-
| [[How_To_Create_Plugins/ExternalDataModelType|ExternalDataModelType]]
|
|-
| [[How_To_Create_Plugins/ProtoFlux_Binding|ProtoFlux Binding]]
| <translate>The binding for a ProtoFlux Node. Without this, a node cannot be loaded into Resonite.</translate>
|-
|}
TODO
 
=== ProtoFlux Node Types ===
{| class="wikitable sortable"
|-
! <translate>Object</translate>
! <translate>Description</translate>
|-
| [[How_To_Create_Plugins/ActionBreakableFlowNode|ActionBreakableFlowNode]]
|
|-
| [[How_To_Create_Plugins/ActionFlowNode|ActionFlowNode]]
|
|-
| [[How_To_Create_Plugins/ActionNode|ActionNode]]
| <translate>A node which runs when called using an impulse</translate>
|-
| AsyncActionBreakableFlowNode
| <translate>Async variant of [[How_To_Create_Plugins/ActionBreakableFlowNode|ActionBreakableFlowNode]]</translate>
|-
| AsyncActionFlowNode
| <translate>Async variant of [[How_To_Create_Plugins/ActionFlowNode|ActionFlowNode]]</translate>
|-
|-
| [[How_To_Write_Plugins/Components|Components]]
| AsyncActionNode
| Used to create custom components
| <translate>Async variant of [[How_To_Create_Plugins/ActionNode|ActionNode]]</translate>
|-
|-
| [[How_To_Write_Plugins/DataModelAssemblyType|DataModelAssemblyType]]
| [[How_To_Create_Plugins/ObjectFunctionNode|ObjectFunctionNode]]
| The type of assembly you are making. Used in your <code>AssemblyInfo.cs</code> file.
| <translate>A ProtoFlux Node which returns a singular object</translate>
|-
|-
| [[How_To_Write_Plugins/ObjectFunctionNode|ObjectFunctionNode]]
| [[How_To_Create_Plugins/ValueFunctionNode|ValueFunctionNode]]
| A ProtoFlux Node which returns a singular object
| <translate>A ProtoFlux Node which returns a singular value</translate>
|-
|-
| [[How_To_Write_Plugins/ProtoFlux_Binding|ProtoFlux Binding]]
| [[How_To_Create_Plugins/VoidNode|VoidNode]]
| The binding for a ProtoFlux Node. Without this, a node cannot be loaded into Resonite.
| <translate>A ProtoFlux Node which doesn't use</translate> <code>return</code> <translate>to give an output. Used for nodes with multiple outputs.</translate>
|-
|-
| [[How_To_Write_Plugins/ValueFunctionNode|ValueFunctionNode]]
|}
| A ProtoFlux Node which returns a singular value
TODO
 
=== Variable types relevant for Components ===
{| class="wikitable sortable"
|-
! <translate>Type</translate>
! <translate>Description</translate>
|-
| [[Type:Sync`1|Sync<T>]]
| <translate>A synced [[:Category:Type:Value|Value]] or [[:Category:Enums|Enum]]</translate>
|-
| [[SyncList`1|SyncList<T>]]
|
|-
| [[Type:SyncRef`1|SyncRef<T>]]
| <translate>A synced [[Reference_Type|Reference]] (object)</translate>
|}
TODO
 
=== Variable types relevant for ProtoFlux Nodes ===
{| class="wikitable sortable"
|-
|-
| [[How_To_Write_Plugins/VoidNode|VoidNode]]
! <translate>Type</translate>
| A ProtoFlux Node which doesn't use <code>return</code> to give an output. Used for nodes with multiple outputs.
! <translate>Description</translate>
|-
|-
|}
|}
TODO


== See also ==
== <translate>See also</translate> ==
* [https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/types/#custom-types Creating custom types in C#]
* <translate>[https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/types/#custom-types Creating custom types in C#]</translate>
<!-- i plan to make a youtube tutorial series at some point! ~ paradox19 (User:Paradox19) -->
<!-- i plan to make a youtube tutorial series at some point! ~ paradox19 (User:Paradox19) -->


[[Category:Tutorial]]
[[Category:Tutorial]]

Latest revision as of 16:23, 6 August 2024

This page may be too technical for most readers to understand. Please help improve it to make it understandable to non-experts, without removing the technical details.

Plugins are used to add more Components and ProtoFlux nodes to Resonite by programming them using C#. They are not to be confused with Mods which do not add things into the Data Model.

This page is about writing plugins and should not be confused with the Plugin overview page.

Please see the plugin guidelines before getting started, to familiarize yourself on what is and is not allowed.

Getting started

You will need to know the basics of the C# Programming Language to write plugins.

  1. Download Visual Studio Community edition, which allows for easier programming and compilation of plugins. However, you can use your favourite code editor as long as you know how to compile C# into a .dll
    • During installation, ensure to select .NET desktop development which will give you the .NET Framework development tools, which are required to compile the plugin
  2. Create a new project using the Class Library template (please ensure it is the C# option). Guidelines follow:
    1. The project name should be the name of your plugin, same with the solution name. It is recommended to not check the box for Place solution and project in the same directory, as you may have multiple parts to your plugin, such as a ProtoFlux Binding generator.
    2. Select the default framework, we'll be manually editing this later.
  3. Add references to the following libraries by right clicking on Dependencies, clicking Add Project Reference and then Browse.
    1. FrooxEngine.dll - Found in Resonite/Resonite_Data/Managed/FrooxEngine.dll
    2. Elements.Core.dll - Found in Resonite/Resonite_Data/Managed/Elements.Core.dll
  4. Change the referenced framework to net462. To do this:
    1. Double click on your project name, this will be under your solution
    2. Change the line <TargetFramework>whatever_you_selected_earlier</TargetFramework> to <TargetFramework>net462</TargetFramework> and save the file
  5. Change Your Assembly Info file to tell FrooxEngine what type of plugin you are making.
    1. Create a folder inside your project called Properties
    2. Create a file called AssemblyInfo.cs which contains the line [assembly: DataModelAssembly(t)], where t is a DataModelAssemblyType.
The framework net462 (step 4) is going to be changed in the future, this will most likely happen with the switch from Unity to Sauce

You're now ready to start writing plugins!

Guides

Components

ProtoFlux

Misc

Object Reference

This section is in a state of significant expansion or restructuring. You are welcome to assist in its construction by editing it as well.
Reason: Doesn't list all types relevant for writing plugins.

Basic Types

Object Description
Components A custom component
DataModelAssemblyType The type of assembly you are making. Used in your AssemblyInfo.cs file.
ExternalDataModelType
ProtoFlux Binding The binding for a ProtoFlux Node. Without this, a node cannot be loaded into Resonite.

TODO

ProtoFlux Node Types

Object Description
ActionBreakableFlowNode
ActionFlowNode
ActionNode A node which runs when called using an impulse
AsyncActionBreakableFlowNode Async variant of ActionBreakableFlowNode
AsyncActionFlowNode Async variant of ActionFlowNode
AsyncActionNode Async variant of ActionNode
ObjectFunctionNode A ProtoFlux Node which returns a singular object
ValueFunctionNode A ProtoFlux Node which returns a singular value
VoidNode A ProtoFlux Node which doesn't use return to give an output. Used for nodes with multiple outputs.

TODO

Variable types relevant for Components

Type Description
Sync<T> A synced Value or Enum
SyncList<T>
SyncRef<T> A synced Reference (object)

TODO

Variable types relevant for ProtoFlux Nodes

Type Description

TODO

See also