Script learning tool

[welk]

I am reading all threads in forum to have a more global view. I have read Modding forum, blog devs, war room, and I will begin the general SC3 WIE forum (76 pages^^)

Reading posts, I noticed that a question was recurrent : how to use scripts. Due to the fact there is no detailled scripting manual, explanations that are in txt templates are not always very clear for players who don't easely read english (it's my case).
And user may be confused with some symbols (; etc) that are not needed in scripts but needed in txt that contains explanations
In addition, explanations themselves may be confused with the real and effective nedded content of script, and to report notes at end of files is not a good pedagogic solution to allow learning : better is to insert each note of explanation in regard of the concerned command line.

In France, we love logic and clarty, like Descartes
So, I decided to create for each script a doc that gives the documentation in a more pedagogic format

It will take some times , but with 1 or 2 in a week, work will progress with regularity

If advanced user of scripts want to do critics, rectifications of errors, etc or to add observations and their own pedagogic/informatives notes or explanations, they are welcome : please, in this case, insert what you want to add in a post and I will insert it in the concerned script doc (do not forget to indicate the concerned script : at this time, there are a few, but others will come)


Attached file : updated this day 19/08/2025
All informations and docs, tips, notes etc are now compiled in a unic global pdf
The doc is now completed, with all event scripts.

I will begin in some days a new doc to do the same with all advanced AI scripts

[BillRunacre]

There are some explanations in Part 2 of the Manual.

[welk]

Thanks, I will read that

For those who want a compilation of "script threads" : https://forums.matrixgames.com/search.p ... mit=Search

[rmelvin]

#ACTIVATE_POSITION= 155,80 [6,6] [x,x] [x]
Hex parameter 6,6 means anything between 0 to 6 hexes.
ACTIVATE_POSITION= 155,80 [6,6] [9,9] [1]
Unit parameters 9,9 means equal to or greater than 9 units within 0 to 6 hexes.
ACTIVATE_POSITION= 155,80 [6,6] [9,12] [1]
Unit parameters 9,12 means random number between 9 thru 12 equal to or greater than units within 0 to 6 hexes.
ACTIVATE_POSITION= 155,80 [6,6] [9,9] [1] [<]
Unit parameters 9,9 < means less than 9 units within 0 to 6 hexes.

I agree about the language; UK English is not the same as American English at times.
Would you like for me to see if I can find in my notes Documentation shortcomings?

[welk]

Thanks for infos, I will integrate that in the concerned scripts docs when I will do their own "pedagogic doc" (I mean scripts with #ACTIVATE_POSITION parameter, the 2 first I did - Annexation and Belligerance - seems not have this kind of parameter)

Concerning notes Documentation : yes, all doc, infos, notes, etc you may have are very interresting and I will integrate them in the "learning scripts docs"

If other scripting specialists like you (I am not, I just learn at this time) could give notes, docs and infos about scripting, it would be nice and they are welcome

I precise : not only "technical informations", but they may give their "art" : example : to explain other player in short note how they do with scripts to simulate usefull events, situations, etc

At the end, we would have a kind of detailled "script school doc" that is missing in game documentation

[welk]

The scripts docs are now contained in a rar file that will stays in first post of this thread and will be updated/completed

[rmelvin]

I think my prior posting works on all _POSITION, if wrong hope Bill corrects

#xxxx_POSITION= xx,xx [x,x] [x,x] [x]

Also, the hex [min,max] if [3,6] not the same number it is a random number from the location hex.

I think it is per turn, also if wrong hope Bill corrects.

[welk]

Thanks for these precisions, I added them : In addition of doc scripts and doc "general reference codes" (with country_id, etc), I created a new doc named : "General notes about scripting" => this doc will contain all tips, general scripting notes, etc that may concern all scripts or some general concept or some general lines command (like POSITION commands), or ways to work in scripting, etc

Rar file in 1st post has been updated
At this time, 3 doc scripts are included, others will follow regulary

If you and other specialists have notes, tips, knowledges to be shared, all is welcome to create this scripting documentation that will probably be usefull for community : you have just to post your notes, tips, etc in this thread with concerned indications/explanations (what script is concerned, or what concept "command line" is concerned, etc)

[welk]

All informations and notes are now displayed in a unic global Pdf (download link is in first post)
The file will be regulary updated, even if no new post here (if interrested by this doc, just needed to consult the first post sometimes to verify if it was updated)

At this time, almost half of total event scripts have been included
Others will follow in some days, and AI script will then also follow

If the doc needs rectifications (errors) or complementary precision : all scripts specialists are welcome to improve this basic documentation

As newbee in scripting, I tried to present all structures scripts in a pedagogic format, that is immediatly usable. If you have any ideas to improve the presentation, please : share them here.

For script specialists : If you have personnal notes about scripting, you may give them here as they are in your own files : no needed to do a specific presentation, I will do that (you have just to copy-past your notes heres, I will do the presentation/organization work)

[welk]

Work does continue, I am reaching the end of the events scrits list, and will update the doc soon and will also begin the AI scripts list

Noticed a little mistake in "notes" for the UNIT script

CITATION:
Units will arrive either within or adjacent to the #DESTINATION_RESOURCE or as close as possible in
; another friendly resource. More than one #DESTINATION_RESOURCE can be listed per event.
;
;
; More than one #DESTINATION_POSITION can be set and the game engine will prioritize from the first
; to the last listed position.
END OF CITATION

I was a little confused with this, because there is no any #DESTINATION_POSITION line in any script "UNIT", before to undertand (I understand slowly ) it was an error : should be written #DESTINATION_RESOURCE


Again, I am calling on all scripting specialists of scripting : if you have notes, tips, docs and informations about scripting, informations about errors and mistakes to avoid, etc : please, share them => I will include them in the public uploadable doc I prepear

Here is a short list of "dummy values" I noticed at this time (dummy values = always satisfied, they allow to avoid tne concerned condition) :

#LINK= 0[0]
#GV= 1[1,100]
#CONDITION_POSITION= 0,0 [0,0] [0,0] [0] [0]
#LEVEL= 0
#NATIONAL_MORALE_TRIGGER= 0 [0] [0]

Seems there is a lot of others, but at this time I did not have time to read all used scripts. Please, if you know other dummy values, give them in a below post.

[welk]

Doc scripts was updated (in the first post) : it does now content all event scripts
Advanced AI scripts will follow a few later

In case of error or mistakes, please report and I will rectify.
Same if you want to add some precisions, informations, etc