Module writing guide?

[Trent R]

Is there a guide or tutorial to writing Modules floating around somewhere? The closest things are the two articles on the wiki, but those are basically just about formatting so there aren't conflicts.


~Trent

[monkey0506]

All you really need to know in order to release a module is how to script. Steal Come up with an idea 8) and then script it. Export the script as an SCM. The end.

Really that's all there is to it. One item that IMO would make it more streamlined and impose less conflicts is to implement a struct as an end-user means of interfacing with your module's functions.

In the Flashlight module, everything the end-user does to run the module's functionality is handled by the FlashlightType struct which has a single imported variable, Flashlight. They can turn the module effect on (Flashlight.Enabled = true;) increase the size of the radius (Flashlight.Radius += 0.5;) etc. all using the struct object.

Another method is using static methods to eliminate the need for a declared object of your struct type. This leans more toward a function-oriented approach as there's no static variables yet.

Aside from that as long as you're not encoding viruses into it, it really is just as simple as writing the code and then providing means for the end-user to take advantage, whether it's imported functions in the header, a struct object, a static struct interface, or whatever.

[SSH]

There's also the Moduel writing guide in the Tech Archive forum...

[poc301]

As I read the initial post, I had the thought : "Does anyone have a tutorial on writing a tutorial?" 

-Bill

[Trent R]

Luckily, many of my questions about writing modules have been answered in this thread. Also, I've been delving into some previously made modules... Most of which have been made by monkey, SSH, KhrisMUC, etc, etc.

I think my biggest confusion is just the differences between other languages and AGS, especially the usual keywords like new or protected. However, I've learned a lot of new things because of AGS(I for the life of me could not figure out enums before)


~Trent

[Trent R]

Been reading through a ton of old threads, and I found this very useful one by monkey. I explains all 'hidden' keywords in AGS.
~Trent
PS-I removed the quotes to better see the code sections. But monkey_05_06 wrote all of this.



static: This keyword refers to a data member or function of a struct that is not called on an instance of a struct, but rather, directly from the struct itself. In the case of data members, only one instance of this member is created no matter how many instances of the struct are implemented.

Code: ags

 struct MyStruct {
  writeprotected int Var; // writeprotected: The user can only read this variable; attempting to modify its value will result in an error. Its value is set by member functions of this struct. See also 'protected'.
  import function SetVar(int value);
  writeprotected static int StaticVar; // won't actually compile (yet), consider using an attribute
  import static function SetStaticVar(int value);
  }

function MyStruct::SetVar(int value) {
  if (value < 0) return;
  this.Var = value;
  }

static function MyStruct::SetStaticVar(int value) {
  if (value < 0) return;
  MyStruct.StaticVar = value; // since there is no instance of the struct, there is no "this" keyword within static functions
  }

MyStruct MyStructInstance;

// game_start
MyStructInstance.SetVar(18);
Display("Var: %d", MyStructInstance.Var);
MyStruct.SetStaticVar(409);                            // note the static function and member
Display("StaticVar: %d", MyStruct.StaticVar); // are called on the struct, not an instance

void: This is a special keyword used only as the return type of a function that returns nothing. These functions are intended simply to carry out a task; no result is returned from the function whatsoever.

Code: ags

void myfunc(int var) {
  if (var < -1093) return; // the return keyword is used by itself to return manually from a function with a void return type as nothing is being returned
  // do stuff
  }

protected: This keyword refers to a data member or member function of a struct that can only be accessed within another member function of the same struct.

Code: ags

struct MyStruct {
  protected int __data__;
  protected import void set_data(int value);
  import void do_something(int value);
  };

protected void MyStruct::set_data(int value) {
  // this function is non-essential, the data could be set directly from the do_something function, this is just an example
  this.__data__ = value;
  }

void MyStruct::do_something(int value) {
  if (value < 0) return;
  this.set_data(value);
  }

// game_start
MyStruct msInstance;
msInstance.do_something(83); // sets the data
msInstance.__data__ = 97; // crashes; data is protected; no read/write access outside of member functions
msInstance.set_data(111); // crashes; function is protected; no access outside of member functions

Regarding the use of static and protected together:

Code: ags

struct MyStruct {
  protected import static int ReturnFive();
  import int GetValue();
  import static int GetItStatically();
  };

protected static int MyStruct::ReturnFive() {
  return 5;
  }

int MyStruct::GetValue() {
  return this.ReturnFive(); // protected members/functions can only be accessed using the 'this' keyword. Although the function is static, it is still possible to access it through an instance
  }

static int MyStruct::GetItStatically() {
  // return MyStruct.ReturnFive(); // crashes; cannot access protected function unless using 'this' keyword which doesn't exist within static function
  // in other words, protected static functions/members are ONLY accessible through a non-static function of the same struct using the 'this' keyword
  }

Regarding writeprotected: This keyword works essentially the same as the protected keyword, except the user is given read access (no write access) to the data member. This keyword applies only to data members. To set a writeprotected member, you must use the same rules as when using protected: You can only modify its value within a non-static function of the same struct, using the this keyword.

private: This is NOT an AGS keyword. It is used in other scripting languages such as C++. See protected instead.

attribute: This is not an officially supported keyword. It is used internally for use with the managed types. It is possible for them to be used for a few purposes, however as its use is not supported, there is no guarantee that your scripts will continue to work with future versions of AGS. Due to ...well...more my lack of interest with this post at this point than anything else really... the advance nature of attributes, I'll withhold an example for now.