Writing scene nodes

[spedler]

@ferdinand

Thanks, I'll look forward to seeing more detail later. I do feel that the scene nodes are very powerful, but as with many things in Cinema their usefulness will be greater if you have some third-party devs expanding what is available. I think the current system will need a lot more high-level nodes added before the majority of artists (as opposed to coders) use them. That's what I'd like to be doing.

Steve

[ferdinand]

Hey @spedler,

First of all, please excuse the slight delay, we are quite busy here at the moment.

So, my information was effectively incorrect. The technology you want to look at are core nodes, as they also support scene nodes. We have this little manual on the subject, and although it says it is only applicable to materials, it effectively is not (I will fix that). We also have this code example for a scene core node (which I totally forgot).

The primary Nodes API examples example.nodes has been written exclusively with material nodes in mind, just as the Nodes API Handbook. But it is certainly also worth having a look at them, as they line out both simple and complex techniques used in all areas of the Nodes API.

What is a bit of a sore spot, is the Resource Editor documentation (just press Shift + C and type "Resou" in Cinema 4D to open it). It is a little bit documented in the Nodes API handbook as well as user documentation but a substantial documentation is missing at the moment.

I would recommend starting out with the user manual and trying to create some node setups with customized interfaces, be it full blown capsules or just interfaces on node groups, to get a feel for the Resource Editor before you start coding. Because just as in the classic API and its .res files, you won't get anywhere without resources.

Cheers,
Ferdinand

[spedler]

Hi @ferdinand,

Many thanks for all the useful info here. I had seen most of it already but it was difficult to pick out which examples were best to start with, so this is very helpful.

I've been experimenting with interfaces and the resource editor using node groups, and I'm gradually getting an idea of how it works. But the process of how to create a new node and its resource is still a bit unclear.

Please correct me if I'm wrong, but as I understand it, the UI for a node is held in a .json file (which Maxon also calls a 'database' from what I can see). Once you have a database you can edit it to define the interface in a new node and the .json file is written out by the resource editor. Am I right so far?

Now the problem is that the nodes API handbook implies that to create the new database (.json file) you need to start Cinema with three command-line parameters as described here. Is this still correct? It seems a bit user-unfriendly if so but I can't find any other way to start the resource editor and create a new database.

Further, the handbook seems to say that you cannot create the node interface in this way until you have a node compiled first, at least a node which registers the (at that point, non-existent) database file. Is this all correct? If so then I've at least begun to understand the process and can start to try to implement something.

Cheers,

Steve

[ferdinand]

Hey @spedler,

with three command-line parameters as described here. Is this still correct?

No, the manual is too strongly worded and also outdated. Mandatory is only one of these flags and one of them does not even exist anymore:

• g_applicationRepositoryWritable=true: Mandatory when you want to add or edit node descriptions.
• g_descriptionEditorDeveloperMode: Not really required as you can also set the value in the resource editor itself, just as shown in the first step in the manual you linked. I am not quite sure why the author included the flag, probably because he liked the convenience of not having to enable the mode every time Cinema 4D does start.
• g_developerNodeEditorFunctions: Does not exist anymore and features are naturally part of Cinema 4D now.

Please correct me if I'm wrong, but as I understand it, the UI for a node is held in a .json file (which Maxon also calls a 'database' from what I can see). Once you have a database you can edit it to define the interface in a new node and the .json file is written out by the resource editor. Am I right so far?

Yes, that is more or less correct. The terminology is a bit all over the place there, but the more common terms are resource and description, just as it was the case in the classic API. With the resource editor your edit your resources, but they are now json and not res files anymore, and in the API these parameter and UI definitions are then expressed as descriptions. Other than in the classic API, the concept of descriptions is however expressed and handled with more than a singular type, the most basic and most compareable type to the classic API type Description is however maxon::DataDescription. But just as in the classic API, you usually do not have to deal with descriptions in detail until you venture into more complex territories.

The reason why the term database pops up here is because node templates, i.e., the metadata bundles which tell Cinema 4D that a node type exists and what its properties are, are stored as assets with the Asset API which operates with the concepts of databases. This is also where the term "application repository" in g_applicationRepositoryWritable comes from, as this is one of the fundamental three asset repositories associated with Cinema 4D:

• Built-in Repository: Contains atomic definitions like data types and very low-level nodes stuff. It is read-only and cannot be changed.
• Application Repository: Contains node templates that have be defined in code, also contains the built-in repository. Is read-only but can be made writable with g_applicationRepositoryWritable.
• User Preferences Repository: Contains (pretty much) all assets that are accessible for a Cinema 4D instance. Also contains the application and with-it built-in repository. Is writable by default for entities that are not part of the non-writeable repos.

As a side note, as this often leads to confusion: We have mixed up a bit the terminology of databases and repositories. When the Asset API talks about repositories as for example with AssetInterface::GetUserPrefsRepository() which returns an UpdatableAssetRepositoryRef, it means the logical interface to data, i.e., what is commonly referred to as a database; with this stuff you can abstractly search for data. When it talks about databases, as for example in AssetDataBasesInterface, it means the physical storage of data, i.e., what is usually referred to as a repository. So, when the resource editor talks about "databases" it just means files on disk just as in the classic API. But there are then later interfaces which view this physical data as a database.

Further, the handbook seems to say that you cannot create the node interface in this way until you have a node compiled first, at least a node which registers the (at that point, non-existent) database file. Is this all correct? If so then I've at least begun to understand the process and can start to try to implement something.

Yes, that is correct. In an upcoming release we will provide an internal interface which enables developers to start coding (the logic of nodes) without having to touch the resource editor. This is then done by deriving the node description from the already necessary MAXON_PORT_INPUT, MAXON_PORT_OUTPUT, etc. definitions. For a finalized UI, you will have still to touch the resource editor, but it will allow you to get started with your logic when you do not care about UI details or how your ports are labeled.

Cheers,
Ferdinand

[spedler]

Hi @ferdinand,

This is great stuff, thanks very much! I'm glad I wasn't too far out in my guesstimate of how it all hung together. I got the example core node built and running but found I couldn't edit the decription. I see now that I have to use the mandatory flag to do that, so I'll give that a try.

Thanks again for your help. I may be back if (when) I run into more issues

Cheers,

Steve

[spedler]

Hm, well as I said I have the example core node running but I can't see its resource because when right-clicking on the node the 'Edit Resource...' entry is not in the context menu. I ran Cinema with this command line:

"C:\Program Files\Maxon Cinema 4D 2023\Cinema 4D.exe" g_applicationRepositoryWritable=true

But it doesn't seem to do anything. I'd expected it to enable editing of the example node, but it doesn't. I can use the resource editor on node groups I've created but not this one. What am I missing?

[ferdinand]

Hey @spedler,

My time to do in-depth support is currently a bit limited due to development duties. When you say

But it doesn't seem to do anything. I'd expected it to enable editing of the example node, but it doesn't.

What do you mean by that? When I try it, stuff seems to be editable just fine, I for example edited the name of the whole resource here (make sure to be in dev mode):

and upon closing that dialog, Cinema 4D will ask you if you want to save that database. When you say yes, the node template will form now on be displayed as follows in the Asset Browser:

As stated earlier, the Resource Editor is not the most well documented thing, and I would recommend starting with the end-user guide I have linked to above when in a pickle.

Cheers,
Ferdinand

[spedler]

Hi @ferdinand,

Thank you for sparing the time you can, I know you must be very busy with other things.

Perhaps I'm going about it the wrong way here. In the node editor, I can drag the Example Core Node from the 'uncategorized' section of the node list into the editor window. To edit the resource for that node, I assumed I would right-click on the example node and somewhere in the context menu, there would be an 'Edit Resource...' entry. That is what happens if I group some nodes together and right-click the group node.

But with the example core node there is no such entry so I can't open the resource editor so can't see or edit the resource. Am I going about this the wrong way? Is there another way to invoke the resource editor?

Steve

[ferdinand]

Hey @spedler,

that should work, but the resource editor is also a bit buggy; although it seems unlikely that there is a bug in that section. But what I did in this case, is I navigated manually to that database. I cannot really create a screen cast for you because the only version with a compiled SDK I have here at the moment is the current alpha.

But what I basically did was:

1. Go to corenode_impl.cpp.
2. Grab the database ID net.maxonexample.nodes_corenodes.module in it.
3. Open the database dropdown in the dialog with its little arrow next to it on the left. The database is the dropdown below "Find Text" and the drop down below that is for the entities in a database.
   
4. Paste in that database name.
5. Select the only entity in it, the "...simplecorenode".

And on the risk of sounding like a broken record, I would really recommend reading the user manual. I know it looks a bit convoluted, but it will still help you.

Cheers,
Ferdinand

PS: I will try to squeeze in some time at the end of this week to retrace my steps with an RC Cinema 4D 2023.X and the RC SDK in case you are then still stuck.

[spedler]

Hi @ferdinand,

I'm sorry but I'm completely stuck here. I'm starting Cinema with the required flag to enable node description editing. I can drag the example core node into the node editor in either scene or material nodes and it works fine.

If I right-click the editor window when in material nodes mode and choose 'Edit Resource...' nothing happens - that is, the resource editor does not open at all. In scene nodes mode, the resource editor does open but I don't see what is shown in your screenshot, what I get is this:

I've been reading the resource editor manual and what I am doing should work, but doesn't, and the screenshots there are different from what I see. I don't get a Mode or Description menu unlike in your screenshot, and I don't see the language drop-down, or the find text button, etc.

I just can't get it to work. Is it possible that your latest build has corrected problems that currently exist in the latest release, or is it just that I am doing something completely wrong? The only thing I can think of is that I am not passing the parameter to Cinema correctly. I'm using a Windows shortcut to start Cinema with this as the target:

"C:\Program Files\Maxon Cinema 4D 2023\Cinema 4D.exe" g_applicationRepositoryWritable=true

Does this look right?

Steve

[ferdinand]

Hey @spedler,

First of all, don't worry, we are happy to help and the Ressource Editor workflow is a bit of a pain in the *** at the moment. From your screenshots it looks a bit like you are clicking on "Edit Port". You should manually navigate to that resource as lined out earlier.

In your case, you would want to select the database net.maxonexample.nodes_corenodes.module as stated earlier, because that is the database the plugin does define. I still do not have an RC with the SDK complied here, but I can show you the the principle:

.

I hope this helps and cheers,
Ferdinand

[spedler]

Hi @ferdinand,

Firstly, thank you very much for this, which is incredibly helpful. I didn't know you had to turn on the ID switch in the editor prefs but more than that, was how to get the resource editor running as you showed in earlier screen shots.

The resource editor manual says that you can right-click in the node editor window and open the resource editor by clicking 'Edit Resource...'. This either does not work at all (if in material mode) or in scene nodes mode opens the resource editor for what looks like the node editor window itself, which isn't very useful. Anyway, there is no menu entry for the resource editor anywhere in the Cinema menu system as far as I can see, or in the node editor menus, so your method of using the commander to open it is the only way to get to it. That is what was confusing me! Now I can open the resource editor and get most of what the screencast shows, although I didn't get the 'Mode' menu so couldn't switch to developer mode. However, adding the 'g_descriptionEditorDeveloperMode=true' flag does work and I can finally see what you show in the screencast - all the menus and switches (Data/UI/String switches) - so that flag is in fact essential ATM with this build of Cinema.

Now I can actually get to the resource editor I can look at the manual for it and see where it goes. I am sorry if I've been so dense in getting this working. It would be nice though if the dev team could look at the issues of how to open the resource editor because it doesn't match the documentation and might well confuse others as well as me.

So for the moment I can now try adding a simple core node of my own based on the example. If I can, I'll try to write some kind of tutorial for this because it's a tricky process as things stand to even get started.

Thanks once again for being so helpful, it is greatly appreciated.

Cheers, Steve