Writing scene nodes

[spedler]

I've been experimenting with the scene nodes in C4D a lot recently and I'm very impressed. I'd like to write some of my own, but I'm not at all sure where to start. There's the nodes API section in the C++ SDK docs, but although it tells you how to do certain things, there doesn't seem to be any step-by-step documentation on building your own nodes. Tantalizingly, the docs state that it is possible to write such nodes...but not how to go about it. There are also the example nodes in the SDK but again, it's not clear how to write your own from scratch.

With an 'ordinary' plugin I'd start by writing a description for it so something appears in the Cinema UI and then hang whatever the functionality was to be on that. But with nodes the 'description' is now in a JSON file and I can't find any docs on the format of that, so it's difficult to get started.

So my question is firstly, are there any resources for writing scene nodes that I have missed. And secondly, if there isn't anything at the moment, does Maxon or anyone else have anything they can share about this? My aim would be to start by writing a very simple function node such as adding two floats (yes I know that already exists but you have to start somewhere) because once the architecture is sorted so the node actually works and appears in the node editor, the rest will follow.

Maybe one place to start is by dissecting one of the example nodes to see how it is built and registered with Cinema? That would in itself be very useful.

Any thoughts would be most welcome.

Steve

[Fremox]

This post is deleted!

[ferdinand]

@Fremox,

Please refrain from disclosing information bound by the NDA in this public forum, no matter how small the infraction might seem; as for example whom is working on what. I have deleted your posting.

@spedler

We will answer later in detail. In short: The public Nodes API access is primarily focused on material nodes at the moment and extending scene nodes is limited. That is at least the last information I have, I will have to ask some of the Nodes API devs what the current state is.

Cheers,
Ferdinand

[Fremox]

@ferdinand

sorry for this, I didn't meant to violate NDA, I was just trying to help.
No problem with the post removal though, will be more careful on that in the future.
Anyway, managing to create my own nodes would interest me as well so I keep following this thread

[ferdinand]

Hey @Fremox,

Don't worry, it is okay, and I know that you just wanted to help but please be a bit more careful in the future.

Cheers,
Ferdinand

[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