T3D1.2: Converting ConsoleMethod to DefineEngineMethod

#1 In engineAPI.h around line 2000 you should find the API Definition Macros - this is where the DefineEngineMethod et. al. macros are. The comments are very informative, unlike the Console Method macros in console.h around line 940.

Hope it's useful!

#2 @Richard,
I am very confused by this engineAPI.h file (line 40):

Quote:
/// @file
/// Definitions for exposing engine functionality to the control layer.
///
/// This file provides a convenience layer around the underlying engine interop system (which at
/// the moment still includes the legacy TorqueScript interop a.k.a. "console system"). The
/// macros exposed here will automatically take care of all marshalling, value type constraints,
/// reflection info instancing, etc. involved in defining engine API call-ins and call-outs.
///
/// @note At the moment, this file supplies both the legacy TorqueScript console system as well
/// as the new engine export system with the structures and information they need. In the
/// near future, the console-based parts will get purged. This will not result in visible
/// changes to users of the functionality here except for the string-based marshalling
/// functions currently exposed (which will also disappear).

What exactly does this mean? Is there a different way to talk to the engine other than the console system? Am I developing to a dead code path with adding external scripting languages? I would rather understand the "new stuff". How does this effect functions in the Con namespace?

Thanks for any info you can provide.

#3 Whoa - Missed that part. The only thing that I'm aware of is that instead of the Console* macros the goal is to move to the DefineEngine* macros. I have only given the entire set a cursory glance, so I can't guess as to the logic behind the decision and I haven't honestly asked anyone. I do remember this being mentioned in the forums some time ago (I want to say late '10 but I'm not certain). There was a period during which the idea of making the script interpreter swappable was batted around but I don't think it really went anywhere.

Might have to ask around a bit this week....

#4 @Richard,
I guess it is some legacy stuff as I have seem different messages about TS recently that said it is not going away. So I will continue down the path I am going and when I release my resource to the community hopefully I can get some constructive guidance and criticism on my efforts. If there is a better way that will be the time to get the information and apply as needed. I realize you really need something to look at before you can really help out.

Thanks for getting back so quick on this. I will try and get an Alpha copy of my resource published so you guys can give me some pointers from an interface perspective. I would hate to get it down perfectly and find out the subsystem I am using is going away in 1.3 or something like that.

#5 Contrary to what that comment block states that Frank pasted, it is impossible to get rid of the legacy TorqueScript console system as it is the only implementation that supports variable number of function call arguments while the newer macros provided since T3D 1.1 (beta1?) do not and cannot possibly support variable amount of arguments. Therefore, the legacy console macros must stay as numerous TorqueScript exposed functions require variable count of arguments to be passed to them and there is no other way to rewrite them.

So, if your writing a function that can accept any number of arguments passed to it then you're stuck with the legacy console macros, else I suggest using the newer TorqueScript exposure macros as they do all the data type conversion for you for both function arguments and return types.

#6 Well, you could pass script objects that would count as one parameter but could hold many fields - I'm just uncertain how to go about sorting that out on the engine side of that call.... lol

#7 This is all striking me as a bit humorous. It led me to the question, "What was the person 'thunking' when they wrote that comment?"

Refer to line 1213 of engineAPI.h if that statement is Greek to you.

#8 Richard: Sure you could workaround by passing a single word or field encoded string to the function, but that would be impractical for functions something like a printf() variant where the prototype is printf(format, ...) which is where ConsoleMethod() comes in handy.

#9 Bear in mind that particular comment block would have been written 2 or more years ago when that would have originally been the plan. I doubt we'll be making such drastic changes to the underlying architecture any time soon.

#10

Quote:

So, if your writing a function that can accept any number of arguments passed to it then you're stuck with the legacy console macros, else I suggest using the newer TorqueScript exposure macros as they do all the data type conversion for you for both function arguments and return types.

"newer TorqueScript exposure macros"? Is this DefineEngineMethod?

#11 @Scott,
I started figuring that was the case after Richard did his double-take. Thanks for clarifying on that.

#12 @Nathan - you are absolutely correct. It would be impractical, and probably just plain annoying to code... lol.

#13 On this following thread the response was very useful for me ;)

www.garagegames.com/community/forums/viewthread/125465

#14 The biggest difference between the old system and the new system is that the new system is designed to easily allow you to expose methods to non-TorqueScript languages.

Quote:Open a Torque 3D DLL in a tool like Dependcy Walker. Note that every export to TorqueScript is also exposed as a external on the DLL.

If you combine that with the information produced by the XML dump of console methods in Engine/source/console/consoleXMLExport.cpp... you should be able to write a tool to generate C# code that calls methods on the Torque DLL. This way C# code can create and call Torque objects in a natural way.

www.garagegames.com/community/blogs/view/21477/1#comment-182367

Quote:My point was is that with that XML dump of classes, function names, and function arguments you can write a small C# program that can automatically build C# wrappers to Torque objects exposed by the DLL.

www.garagegames.com/community/blogs/view/21477/1#comment-182376

#15 Ahh, you all are in my world atm...

I've researched this stuff pretty heavily, and it appears, that at some time in the past, they were trying to make all the console functions, etc exportable to extern function calling so you could swap out the console.

Thus, the new syntax, because the old syntax could not be effectively mapped to an extern. (I tried also to convert them using my parser and it proved very difficult). So, the new(er) format through the trampoline (which doesn't work) exposes your engine methods outside the torque dll.

@Nathan
As with having multiple parameters, your statement is is not quite correct, because you CAN specify default values for parameters. So in the case of a printf your could add 20 string params to the end and default the to empty quotes.

Personally, I think the main reason they abandoned the console swapability (is it a word?) was because some of the legacy code could not be converted easily without major reworkings. I.E. any function exposed via a engine define would need a header file, (to work properly) and there is a good bit of network and graphics and audio C++ files which lack headers.

I managed to work around a lot of this, but I basically had to hand code all the old style console methods by hand and I was able to bulk import 99 percent of the DefineEngine methods.

The final work around for me was just extending the torque console instead of replacing it. I figure they were really scratching their heads when they were trying to figure out how to do "Parent::" type of functionality.

Vince

#16 @all:

Bumping this thread, as it is even more relevant with 3.6+...

...per the original post (before it got hijacked), if anyone has guidlines/advice for converting ConsoleMethods from older versions to DefineEngine methods, I'd be most grateful.

#17 First, variadic templates are now available! That means the way that the current set of DefineEngine* wranglers are no longer needed the way that they are now - you can make a single call that takes a variable number of template parameters.

As for how to convert them, I haven't looked at them in a very long time and can't give any really cogent advice without looking into it for a bit myself.

#18 Does that mean that the Console* can finally be removed? I kinda liked that system :( heh

#19 @Richard: I see many were converted for 3.6+, just wondering if there's any 'tricks'...

#20 Hello,i want to write a tool to generate C# code 2 of 5 and i am confuseD with ConsoleMethod and DefineEngineMethod.I wish to know what is the difference between ConsoleMethod and DefineEngineMethod? I'm not sure to understand but the both create a console access to referenced object in the engine i think.