added __on_start and defined better meta-events

docs/scarpet/api/Events.md

@@ -27,11 +27,32 @@ Here is a list of events that are handled by default in scarpet. This list inclu
 to autoload them, but you can always add any function to any event (using `/script event` command)
 if it accepts required number of parameters.
 
+## Meta-events
+
+These events are not controlled / triggered by the game per se, but are important for the flow of the apps, however for all 
+intent and purpose can be treated as regular events. Unlike regular events, they cannot be hooked up to with 'handle_event',
+but the apps themselves need to have them defined as distinct function definitions, same they cannot be signalled.
+
+### `__on_start()`
+Called once per app in its logical execution run. For `'global'` scope apps its executed right after the app is loaded. For
+`'player'` scope apps, it is triggered once per player before the app can be used by that player. Since each player app acts
+independently from other player apps, this is probably the best location to include some player specific initializations. Static
+code (i.e. code typed directly in the app code that executes immediately, outside of function definitions), will only execute once
+per app, regardless of scope, `'__on_start()'` allows to reliably call player specific initializations.
+
+### `__on_close()`
+
+Called once per app when the app is closing or reloading, right before the app is removed. 
+For player scoped apps, its called once per player. Scarpet app engine will attempt to call `'__on_close()'` even if
+the system is closing down exceptionally. 
+ 
+
 ## Built-in global events
 
 Global events will be handled once per app that is with `'global'` scope. With `player` scoped apps, each player instance
  is responsible independently from handling their events, so a global event may be executed multiple times for each player.
 
+
 ### `__on_server_starts()`
 Event triggers after world is loaded and after all startup apps have started. It won't be triggered with `/reload`.
 

docs/scarpet/api/Overview.md

@@ -13,6 +13,11 @@ When loaded (via `/script load` command, etc.), the game will run the content of
 `__config()` function, if present, which will be executed once. Loading the app will also bind specific 
 events to the event system (check Events section for details).
  
+If an app defines `__on_start()` function, it will be executed once before running anything else. For global scoped apps,
+this is just after they are loaded, and for player scoped apps, before they are used first time by a player.
+Unlike static code (written directly in the body of the app code), that always run once per app, this may run multiple times if
+its a player app nd multiple players are on the server. 
+ 
 Unloading an app removes all of its state from the game, disables commands, removes bounded events, and 
 saves its global state. If more cleanup is needed, one can define `__on_close()` function which will be 
 executed when the module is unloaded, or server is closing or crashing. However, there is no need to do that