Coh3n
2014-01-12 12:32:33
How to add the SRL Player Form to your script
Introduction
[INDENT]
Hello! I am going to teach you how to add the new SRL player form (SPF) to any script. The SPF is a very customizable user interface that helps script users setup your script. You can have as many or as few player settings as you wish, as well has some other optional properties. I highly recommend adding the SPF to all your scripts - it's simple and makes setting up your script much easier for users. Please read this guide carefullly; it may be confusing.
This guide assumes you have a decent knowledge of arrays and custom records.
[/INDENT]
Features
[INDENT]
As stated above, there is a lot of room for customization. If you'd like a feature added, please suggest it here.
Features:
- Automatically loads all user's player files into the "Player File" combo box.
- Automatically loads a user's previous settings.
- Scripters can have as many TEdits, TComboBoxes, and TCheckBoxes as they wish.
- Scripters have the option to set default values for each of the above components.
- The PlayerForm variable has several attributes that can be customized by the scripter.
[/INDENT]
Added SPF to a script
[INDENT]
The SPF can be added to any script in a few easy steps:
- Include the Simba file in your script.
- Create the SPF init() procedure.
- Create the modified decalarePlayers() procedure.
- Debug the results (optional)!
- Call runPlayerForm() in your mainloop.
Including it in your script[INDENT]
Very simple step, just add the following to the top of your script:
program new;
{$DEFINE SMART}
{$i srl-6/srl.simba}
{$i srl-6/lib/misc/srlplayerform.simba} // include the file AFTER srl.simba
Create the SPF init() procedure[INDENT]
This is the procedure that declares the SPF settings. In this procedure, you're modifying the "playerForm" variable to your liking. Here's an example procedure explained:
// initiates the SRL player form (you aren't restricted to the procedure name; it can be whatever you want)
procedure initPlayerForm();
begin
with playerForm do
begin
name := 'SRL Player Form ~ Test'; // the title of the SPF, usually the name of your script
scriptHelpThread := ''; // a link to a help thread, if set to '' will link to my setup guide
editBoxLabels := ['Minutes to run', 'Logs to Chop', 'Minutes before breaking']; // edit boxes are created for each array element
editBoxDefaults := ['0', '0', '0']; // optional default values for each edit box; array length must equal editBoxLabel length
// optional hints for each edit box; hints are shown when the user holds the mouse over the component
editBoxHints := ['How long to run (in minutes)?', 'How many logs do you want to chop?', 'Run for this amount of time (in minutes) before breaking.'];
checkBoxLabels := ['Hatchet Equipped', 'Save SRL log', 'Draw on SMART']; // same as editBoxLabels but for check boxes
checkBoxDefaults := ['True', 'True', 'False'];
checkBoxHints := ['Is your hatchet equipped?', 'Do you want to save SRL debug to a log file (recommended)?', 'Do you want do draw some debug information on SMART?'];
comboBoxLabels := ['Tree Type']; // same as editBoxLabels but for combo boxes (drop down boxes)
comboBoxDefaults := ['Willow'];
comboBoxHints := ['Choose the type of tree you want to chop.'];
// this needs to be done for every element in the comboBoxLabels array
setLength(comboBoxItems, length(comboBoxLabels));
comboBoxItems[0] := ['Normal', 'Oak', 'Willow', 'Maple', 'Yew', 'Magic']; // all the options available for the first combo box
end;
end;
[/INDENT]
Create the modified declarePlayers() procedure[INDENT]
This procedure is essential, and I highly recommend debugging player information when you think you're finished. This is the procedure that sets all player information based on an array from the SPF. You don't want to accidentally set a player setting to the wrong data. The player's settings are stored in the "playerForm.players.settings" variable.
The key to this procedure is properly accessing the player's settings that were set by the SPF. Each player will have an array of settings associated with them that were set in the SPF. These settings are all in strings, so they need to be converted when you set different typed attributes. Here's an example explained:
// again, not restricted to the procedure name, although it's recommended
procedure declarePlayers();
var
i: integer;
begin
players.setup(playerForm.players); // load the SPF players from the SRL Player Manager
currentPlayer := 0; // player to use first
// set player attributes based on the settings from the form
for i := 0 to high(players) do
with players[i] do
begin
// convert the integers
integers[0] := strToInt(playerForm.players[i].settings[0]);
integers[1] := strToInt(playerForm.players[i].settings[1]);
integers[2] := strToInt(playerForm.players[i].settings[2]);
// booleans
booleans[0] := strToBool(playerForm.players[i].settings[3]);
booleans[1] := strToBool(playerForm.players[i].settings[4]);
booleans[2] := strToBool(playerForm.players[i].settings[5]);
// strings
strings[0] := playerForm.players[i].settings[6];
// any other data types you've decided to use
end;
end;
[/INDENT]
Debug the results (optional)[INDENT]
Although optional, it is highly recommended. This ensures that everything was properly set in your modified declarePlayers() procedure. Here's an example debug procedure for the above SPF:
procedure debugSPFSettings();
var
i: integer;
begin
writeln('');
for i := 0 to high(players) do
begin
writeln('Minutes to run: ', players[i].integers[0]);
writeln('Logs to chop: ', players[i].integers[1]);
writeln('Minutes before breaking: ', players[i].integers[2]);
writeln('Hatchet Equipped: ', players[i].booleans[0]);
writeln('Save SRL log: ', players[i].booleans[1]);
writeln('Draw on SMART: ', players[i].booleans[2]);
writeln('Tree Type: ', players[i].strings[0]);
writeln('');
end;
end;
Minutes to run: 0
Logs to chop: 6000
Minutes before breaking: 70
Hatchet Equipped: True
Save SRL log: False
Draw on SMART: True
Tree Type: Willow
[/INDENT]
Call runPlayerForm() in your mainloop[INDENT]
Another important step. If you don't do this, nothing will work. :p You simply need to call the correct procedures before setupSRL() and you're good to go. Example:
begin
clearDebug();
initPlayerForm(); // initiate your settings
runPlayerForm(); // run the form
// use this so the script doesn't continue if the user exits out of the form
if (not playerForm.isScriptReady) then
exit;
declarePlayers();
debugSPFSettings(); // this can be removed if you're satisfied with the result
setupSRL();
end.
[/INDENT]
Conclusion
[INDENT]
I hope this was easy enough to understand. If you have any questions and/or concerns, please feel free to post here and I will help you out the best I can. I have also attached the complete example script if you'd like to use test it.
Cheers,
Coh3n
[/INDENT]
[/INDENT]
