SRL Archive - Extensions

Welcome!

In this tutorial you will learn how to make an extension for Simba.
Before starting this tutorial, you should already know how to make a script in Simba, and you should know the difference between a procedure and a function.

1. What is an extension?
2. What can you use it for?
3. How do we make one?

1. What is an extension?
An extension is an add-on to Simba, it can be anything as basic as telling you what the time is (Which we'll be making in this tutorial), to advanced stuff like a dtm editor.

If you have the newest Simba and the newest extensions, then I am sure you have an extension named "security.sex".
If you enable this, you will get an additional 'option' in the drop-down menu "Tools" on the toolbar.
The new option is named "Security", and when hovered you can choose between enabling Security or looking at the settings.

Simba extensions are scripts written for the interpreter that can be embedded into Simba.

From: Simba Documentation
Extensions are event based. This means you don’t have some loop in your program that never ends and does all the logic for you. When a system is event based, you implement some functions and those are called on a certain event.

2. What can you use it for?
Your extension can do all the things a normal script can (Although, you don't want to make your RS scripts into extensions.. That's what the extension "Script Manager" is for ;) (Coming soon)).
We will in this tutorial make an extension that can output the time into the debug box.

3. How do we make one?
There is no difference in the coding between coding a script and an extension. You can even use Simba to test your extension.

First you have to think out an idea for the extension, then it is smart to make a plan on how to go forth.

Now, because We'll be making such a basic extension, we don't have to do much planning. This is the plan I made:
1. Tell the user that the extension has started. You don't want your extension not to alert the user about what's happening.
2. Do the thing. Output the time into the debug box.
3. Tell the user that the extension is finished doing what it was designed for.

There is some procedures and functions that you have to include in your extension.
These procedures and functions is named Init, Free, Attach, Detach, GetName and GetVersion. It might look like a big list, but you'll see that they wont take up much code.

I think it's time to start making our extension.
Open a new script in Simba. It should look like this already:

program new;
begin
end.

Change the name of the program to something smarter than 'new' and add some spacing for our procedures and functions.

program TimeExtension;






begin // Main Loop
end.

First we'll add the functions GetName and GetVersion.
These functions are used to tell Simba what the extensions name and version is.

program TimeExtension;




function GetName : String;
begin;
  Result := 'Time_Extension';
end;

function GetVersion : String;
begin;
  Result := '0.1';
end;  

begin // Main Loop
end.

Now Simba would know what the name and the version of our extension is. Next we'll add the procedures Attach and Detach.
These procedures are used when the user enables (attaches) or disables (detaches) the extension using Simba's extension viewer (View -> Extension).

program TimeExtension;


procedure Attach;
begin;
  // When the extension is enabled, this procedure will be run.
  // If the extension was already enabled when Simba started, this procedure
  //   will be run (It will run after Init;).
  Writeln('TimeExtension Attached/Enabled.');
end;

Procedure Detach;
begin
  // When the extension is disabled, this procedure will be run.
  WriteLn('TimeExtension Detached/Disabled.');
end;  

function GetName : String;
begin;
  Result := 'Time_Extension';
end;

function GetVersion : String;
begin;
  Result := '0.1';
end;  

begin // Main Loop
end.

The last procedures we'll add is Init and Free. "Init;" is used as the "main loop" of the extension, and "Free;" Is used to free all the objects and bitmaps you have loaded inside Init; (If any). Usually when Simba is closed.

program TimeExtension;

procedure Free;
begin
  // Here you free all the objects, bitmaps, dtms and whatnot.
end;

procedure Init;
begin;
  // This is what you want SIMBA to do on start-up.
  WriteLn('The time is: ' );
end;  

procedure Attach;
begin;
  // When the extension is enabled, this procedure will be run.
  // If the extension was already enabled when Simba started, this procedure
  //   will be run (It will run after Init;).
  Writeln('TimeExtension Attached/Enabled.');
end;

Procedure Detach;
begin
  // When the extension is disabled, this procedure will be run.
  WriteLn('TimeExtension Detached/Disabled.');
end;  

function GetName : String;
begin;
  Result := 'Time_Extension';
end;

function GetVersion : String;
begin;
  Result := '0.1';
end;  

begin // Main Loop
end.

As you can see, I already added code to the Init; procedure, but as it is right now, it wont output the time.
Now we add the remaining code in the Init; procedure and our extension is done!

program TimeExtension;

procedure Free;
begin
  // Here you free all the objects, bitmaps, dtms and whatnot.
end;

procedure Init;
var
  H, M, S : Integer;
begin;
  // This is what you want SIMBA to do on start-up.
  ConvertTime(GetSystemTime, H, M, S);
  WriteLn('The time is: ' + IntToStr(H) + ':' + IntToStr(M) + ':' + IntToStr(S));
end;  

procedure Attach;
begin;
  // When the extension is enabled, this procedure will be run.
  // If the extension was already enabled when Simba started, this procedure
  //   will be run (It will run after Init;).
  Writeln('TimeExtension Attached/Enabled.');
end;

Procedure Detach;
begin
  // When the extension is disabled, this procedure will be run.
  WriteLn('TimeExtension Detached/Disabled.');
end;  

function GetName : String;
begin;
  Result := 'Time_Extension';
end;

function GetVersion : String;
begin;
  Result := '0.1';
end;  

begin // Main Loop
end.

NOTE:

From: Simba Documentation
Extensions can be very dangerous in the sense that they run on the main thread of Simba; it is very easy to crash Simba or cause it to hang. There is no way to prevent this, so make sure to check what you’re doing before you try your own (or someone else’s) extension.

Now we have to test our extension. There is two ways to do it.
The first (And the most basic one) is to add it to Simba's extensions.
You do so by saving it as a .sex file. In this case we'll save it as TimeExtension.sex. Save it inside Simba/Extension.
Now restart Simba and look for "The time is: " In the debug box
You have now made your very first extension! Congratulations! :D

The second one is to add some code do the main loop of our extension.

In order to make it work as an extension and still be able to test it inside Simba, we'll have to use Define commands. If you do not know what this is then you can ignore this part and do the first option.

This is the code I use to test my functions:

  {$IFNDEF EXTENSION}
  Attach;
  Init;
  Free;
  Detach;
  {$ENDIF}

I add that to my main loop and the finished product is this:

program TimeExtension;

procedure Free;
begin
  // Here you free all the objects, bitmaps, dtms and whatnot.
end;

procedure Init;
var
  H, M, S : Integer;
begin;
  // This is what you want SIMBA to do on start-up.
  ConvertTime(GetSystemTime, H, M, S);
  WriteLn('The time is: ' + IntToStr(H) + ':' + IntToStr(M) + ':' + IntToStr(S));
end;  

procedure Attach;
begin;
  // When the extension is enabled, this procedure will be run.
  // If the extension was already enabled when Simba started, this procedure
  //   will be run (It will run after Init;).
  Writeln('TimeExtension Attached/Enabled.');
end;

Procedure Detach;
begin
  // When the extension is disabled, this procedure will be run.
  WriteLn('TimeExtension Detached/Disabled.');
end;  

function GetName : String;
begin;
  Result := 'Time_Extension';
end;

function GetVersion : String;
begin;
  Result := '0.1';
end;  

begin // Main Loop
  {$IFNDEF EXTENSION}
  Attach;
  Init;
  Free;
  Detach;
  {$ENDIF}
end.

You have now made your very first extension! Congratulations! :D
Now to enable it, save it as a .sex file (if you haven't done so already).
Restart Simba and go to View -> Extensions and enable the extension!

Thanks for reading :)

USEFUL LINK(s):
http://wizzup.org/simbadoc/simbaref/extensions.html

Great job mate! Was very interested in this subject! :)

ooo… well done, now i know how to make extensions :)

~shut

FYI: Init is called before Attach, and Free is called after Detach. :)
E: There's also this; http://wizzup.org/simbadoc/simbaref/extensions.html

as you wrote a tutorial on extensions, maybe you can help me with this
http://villavu.com/forum/showthread.php?t=58079

~shut

Thanks Hermen and shut! :)

From: Wizzup?
FYI: Init is called before Attach, and Free is called after Detach. :)
E: There's also this; http://wizzup.org/simbadoc/simbaref/extensions.html

Oh..! Thanks! :P
I'll add information from that file to this tut