Differences

This shows you the differences between two versions of the page.

--- tutorials:advanced:create-module-lib [2025/04/02 15:39] – [Use a module lib] gaetan
+++ tutorials:advanced:create-module-lib [2025/04/02 16:26] (current) – gaetan
@@ Line 2: / Line 2: @@
 In this tutorial we will cover how to create, and use module libraries (which are compiled libraries of groimp projects).
+====== Create an example project ======
+Let's create a very simple project from the ''newRGG'' template.
+**Rename the Model.rgg file to An.rgg** (or any other name). It is not required but it gets confusing when all modules come from Model classes.
+Let's include a custom shader from an image to the project (steps correspond to image bellow):
+  - Open the image explorer
+  - Import any image
+  - Create a new shader in the shader explorer
+  - In the attribute editor edit the shader to use the imported image
+{{:tutorials:advanced:shader_from_img.png?400|}}
+Now, let's use this shader on the ''module A'' in the project:
+<code java>
+module A(float len) extends Sphere(0.1)
+{
+	{setShader(shader("testshader"));} // testshader is the name you gave to the shader created
+}
+</code>
 ===== Export =====
-To export a project as a library, the project needs to be currently opened. Then, from the GUI a menu is available under ''File>Export as Module lib''.
+We can now export the current project as a module library. Click on the menu ''File>Export as Module library''.
+{{:tutorials:advanced:export_module_lib.png?400|}}
 ==== Package name ====
+You will need to provide a package name. The package name NEEDS to follow java specifications on package names (no weird characters). The package name will be used to identify the library with an unique name.
+Let's use ''pkg.example''.
 ==== Plugin name ====
+You will need to provide a Plugin name. This name will be used when accessing the resources from this library.
+The combination of package name + plugin name needs to be unique for GroIMP.
+Let's use ''Test''.
+==== Select a directory ====
+You decide where the project is exported to. The creation of a module lib create three or four files (depending on whether the project contains resources or not).
+  * A plugin.xml file - contains the information for GroIMP on how to load the library
+  * A plugin.property file - contains the additional properties for the library (its name).
+  * A .jar file - contains the compiled classes.
+  * A .grz file - contains the resources.
 ===== Import =====
+Now that the module library has been created, we can adds it to GroIMP as a plugin.
+==== Add lib to GroIMP ====
+Create a directory with the name of your library (''Test'' in this tutorial), and add the 4 files in it.
+Move the directory in the GroIMP [[:dev-guide:plugins|plugin directory]] (''~/.grogra.de-platform/plugins/'' by default on debian).
+Then, restart GroIMP to load the library.
+Now let's open a new project (''newRGG'' for instance).
 ==== Type ====
+The types from the module library can be imported in the project like any other classes:
+''import pkg.example.An.A;''.
+The pattern is: ''import {package name}.{File name}.{Class/module name};''.
+Notice that the name of the file is required in the import. GroIMP implicitly create classes with the name of the files to wrap all types defined in .rgg classes.
+**Note:** in the ''newRGG'' project, if you import ''An.A'', "nothing" visible will happen. Because the project also declare a type called ''A''. So, in order to adds An.A to the project you can either use its full name, or hide (by deleting?) the module A declaration.
+The Node An.A have the shader from their original project, i.e. the one with the image.
 ==== Resources ====
+Resources from module lib can also be used without classes. You can use the shader ''testshader'' on any module in your project with:
+<code java>
+module A(float len) extends Sphere(0.1)
+{
+	{setShader(shader("plg:pkg.example.Test:testshader"));}
+}
+</code>
+The Shader reference use the path: ''plg:{package name}.{plugin name}:{resource name}''.