Engine: use abstract types in plugin API instead of exposing internals

Only palette is left for now, deal with that later.

Common/ac/characterinfo.h

@@ -47,7 +47,7 @@ using namespace AGS; // FIXME later
 #define FOLLOW_ALWAYSONTOP  0x7ffe
 
 struct CharacterExtras; // forward declaration
-// remember - if change this struct, also change plugin header file struct
+
 struct CharacterInfo {
     int   defview;
     int   talkview;

Common/ac/mousecursor.h

@@ -22,7 +22,7 @@ using namespace AGS; // FIXME later
 #define MCF_DISABLED 2
 #define MCF_STANDARD 4
 #define MCF_HOTSPOT  8  // only animate when over hotspot
-// this struct is also in the plugin header file
+
 struct MouseCursor {
     int   pic;
     short hotx, hoty;

Engine/ac/gamestate.h

@@ -62,7 +62,6 @@ struct GameState {
     int  fast_forward;           // player has elected to skip cutscene
     int  room_width;      // width of current room (320-res co-ordinates)
     int  room_height;     // height of current room (320-res co-ordinates)
-    // ** up to here is referenced in the plugin interface
     int  game_speed_modifier;
     int  score_sound;
     int  takeover_data;  // value passed to RunAGSGame in previous game

Engine/ac/roomobject.h

@@ -23,8 +23,6 @@
 namespace AGS { namespace Common { class Stream; }}
 using namespace AGS; // FIXME later
 
-// This struct is only used in save games and by plugins
-// [IKM] Not really.... used in update loop
 struct RoomObject {
     int   x,y;
     int   transparent;    // current transparency setting

Engine/plugin/agsplugin.cpp

@@ -61,6 +61,7 @@
 #include "ac/dynobj/scriptstring.h"
 #include "main/graphics_mode.h"
 #include "gfx/gfx_util.h"
+#include "ac/dynobj/scriptobject.h"
 
 using namespace AGS::Common;
 using namespace AGS::Engine;
@@ -119,6 +120,7 @@ extern PluginObjectReader pluginReaders[MAX_PLUGIN_OBJECT_READERS];
 extern int numPluginReaders;
 extern RuntimeScriptValue GlobalReturnValue;
 extern ScriptString myScriptStringImpl;
+extern ScriptObject scrObj[MAX_INIT_SPR];
 
 // **************** PLUGIN IMPLEMENTATION ****************
 
@@ -362,11 +364,13 @@ void IAGSEngine::PollSystem () {
 AGSCharacter* IAGSEngine::GetCharacter (int32 charnum) {
     if (charnum >= game.numcharacters)
         quit("!AGSEngine::GetCharacter: invalid character request");
-
+    // IMPORTANT: if we change the script functions object argument type, we must change this return value too!
     return (AGSCharacter*)&game.chars[charnum];
 }
 AGSGameOptions* IAGSEngine::GetGameOptions () {
-    return (AGSGameOptions*)&play;
+    // We should not return anything, because script functions do not require passing actual instance of GameState
+    quit("!AGSEngine::GetGameOptions() is no longer supported. Use related script API instead.");
+    return NULL;
 }
 AGSColor* IAGSEngine::GetPalette () {
     return (AGSColor*)&palette[0];
@@ -398,8 +402,8 @@ int IAGSEngine::GetNumObjects () {
 AGSObject *IAGSEngine::GetObject (int32 num) {
     if (num >= croom->numobj)
         quit("!IAGSEngine::GetObject: invalid object");
-
-    return (AGSObject*)&croom->obj[num];
+    // IMPORTANT: if we change the script functions object argument type, we must change this return value too!
+    return (AGSObject*)&scrObj[num];
 }
 BITMAP *IAGSEngine::CreateBlankBitmap (int32 width, int32 height, int32 coldep) {
 	// [IKM] We should not create Bitmap object here, because
@@ -429,16 +433,10 @@ BITMAP *IAGSEngine::GetRoomMask (int32 index) {
         quit("!IAGSEngine::GetRoomMask: invalid mask requested");
     return NULL;
 }
+// [DEPRECATED]
 AGSViewFrame *IAGSEngine::GetViewFrame (int32 view, int32 loop, int32 frame) {
-    view--;
-    if ((view < 0) || (view >= game.numviews))
-        quit("!IAGSEngine::GetViewFrame: invalid view");
-    if ((loop < 0) || (loop >= views[view].numLoops))
-        quit("!IAGSEngine::GetViewFrame: invalid loop");
-    if ((frame < 0) || (frame >= views[view].loops[loop].numFrames))
-        return NULL;
-
-    return (AGSViewFrame*)&views[view].loops[loop].frames[frame];
+    quit("!AGSEngine::GetViewFrame() is no longer supported. Use Game_GetViewFrame() of the script API instead.");
+    return NULL;
 }
 int IAGSEngine::GetRawPixelColor (int32 color) {
     // Convert the standardized colour to the local gfx mode color
@@ -535,10 +533,9 @@ void IAGSEngine::MarkRegionDirty(int32 left, int32 top, int32 right, int32 botto
     plugins[this->pluginId].invalidatedRegion++;
 }
 AGSMouseCursor * IAGSEngine::GetMouseCursor(int32 cursor) {
-    if ((cursor < 0) || (cursor >= game.numcursors))
-        return NULL;
-
-    return (AGSMouseCursor*)&game.mcurs[cursor];
+    // We should not return anything, because (at this time) script functions do not require actual cursor instance
+    quit("!AGSEngine::GetMouseCursor() is no longer supported. Use related script API instead.");
+    return NULL;
 }
 void IAGSEngine::GetRawColorComponents(int32 coldepth, int32 color, int32 *red, int32 *green, int32 *blue, int32 *alpha) {
     if (red)

Engine/plugin/agsplugin.h

@@ -79,126 +79,17 @@ struct AGSColor {
   unsigned char padding;
 };
 
-struct AGSGameOptions {
-  int32 score;      // player's current score
-  int32 usedmode;   // set by ProcessClick to last cursor mode used
-  int32 disabled_user_interface;  // >0 while in cutscene/etc
-  int32 gscript_timer;    // obsolete
-  int32 debug_mode;       // whether we're in debug mode
-  int32 globalvars[50];   // obsolete
-  int32 messagetime;      // time left for auto-remove messages
-  int32 usedinv;          // inventory item last used
-  int32 inv_top,inv_numdisp,inv_numorder,inv_numinline;
-  int32 text_speed;       // how quickly text is removed
-  int32 sierra_inv_color; // background used to paint defualt inv window
-  int32 talkanim_speed;   // animation speed of talking anims
-  int32 inv_item_wid,inv_item_hit;  // set by SetInvDimensions
-  int32 speech_text_shadow;         // colour of outline fonts (default black)
-  int32 swap_portrait_side;         // sierra-style speech swap sides
-  int32 speech_textwindow_gui;      // textwindow used for sierra-style speech
-  int32 follow_change_room_timer;   // delay before moving following characters into new room
-  int32 totalscore;           // maximum possible score
-  int32 skip_display;         // how the user can skip normal Display windows
-  int32 no_multiloop_repeat;  // for backwards compatibility
-  int32 roomscript_finished;  // on_call finished in room
-  int32 used_inv_on;          // inv item they clicked on
-  int32 no_textbg_when_voice; // no textwindow bgrnd when voice speech is used
-  int32 max_dialogoption_width; // max width of dialog options text window
-  int32 no_hicolor_fadein;      // fade out but instant in for hi-color
-  int32 bgspeech_game_speed;    // is background speech relative to game speed
-  int32 bgspeech_stay_on_display; // whether to remove bg speech when DisplaySpeech is used
-  int32 unfactor_speech_from_textlength; // remove "&10" when calculating time for text to stay
-  int32 mp3_loop_before_end;    // loop this time before end of track (ms)
-  int32 speech_music_drop;      // how much to drop music volume by when speech is played
-  int32 in_cutscene;            // we are between a StartCutscene and EndCutscene
-  int32 fast_forward;           // player has elected to skip cutscene
-  int32 room_width;      // width of current room (320-res co-ordinates)
-  int32 room_height;     // height of current room (320-res co-ordinates)
-};
-
-// AGSCharacter.flags
-#define CHF_NOSCALING       1
-#define CHF_FIXVIEW         2     // between SetCharView and ReleaseCharView
-#define CHF_NOINTERACT      4
-#define CHF_NODIAGONAL      8
-#define CHF_ALWAYSIDLE      0x10
-#define CHF_NOLIGHTING      0x20
-#define CHF_NOTURNING       0x40
-#define CHF_NOWALKBEHINDS   0x80
-
-struct AGSCharacter {
-  int32 defview;
-  int32 talkview;
-  int32 view;
-  int32 room, prevroom;
-  int32 x, y, wait;
-  int32 flags;
-  short following;
-  short followinfo;
-  int32 idleview;           // the loop will be randomly picked
-  short idletime, idleleft; // num seconds idle before playing anim
-  short transparency;       // if character is transparent
-  short baseline;
-  int32 activeinv;
-  int32 talkcolor;
-  int32 thinkview;
-  int32 reserved[2];
-  short walkspeed_y, pic_yoffs;
-  int32 z;
-  int32 reserved2[5];
-  short loop, frame;
-  short walking, animating;
-  short walkspeed, animspeed;
-  short inv[301];
-  short actx, acty;
-  char  name[40];
-  char  scrname[20];
-  char  on;
-};
-
-// AGSObject.flags
-#define OBJF_NOINTERACT 1     // not clickable
-#define OBJF_NOWALKBEHINDS 2  // ignore walk-behinds
-
-struct AGSObject {
-  int32 x,y;
-  int32 transparent;    // current transparency setting
-  int32 reserved[4];
-  short num;            // sprite slot number
-  short baseline;       // <=0 to use Y co-ordinate; >0 for specific baseline
-  short view,loop,frame; // only used to track animation - 'num' holds the current sprite
-  short wait,moving;
-  char  cycling;        // is it currently animating?
-  char  overall_speed;
-  char  on;
-  char  flags;
-};
+// These are pointer types returned from the engine, to be used only as
+// arguments when calling script functions. The contents of these types are
+// sealed from plugins. You do not need to know what is inside these structs,
+// nor try to access their data in your plugin code, because it may be
+// a subject of change in any future engine update.
+struct AGSGameOptions;
+struct AGSCharacter;
+struct AGSObject;
+struct AGSViewFrame;
+struct AGSMouseCursor;
 
-// AGSViewFrame.flags
-#define FRAF_MIRRORED  1  // flipped left to right
-
-struct AGSViewFrame {
-  int32 pic;            // sprite slot number
-  short xoffs, yoffs;
-  short speed;
-  int32 flags;
-  int32 sound;          // play sound when this frame comes round
-  int32 reserved_for_future[2];
-};
-
-// AGSMouseCursor.flags
-#define MCF_ANIMATEMOVE 1
-#define MCF_DISABLED    2
-#define MCF_STANDARD    4
-#define MCF_ONLYANIMOVERHOTSPOT 8
-
-struct AGSMouseCursor {
-  int32 pic;            // sprite slot number
-  short hotx, hoty;     // x,y hotspot co-ordinates
-  short view;           // view (for animating cursors) or -1
-  char  name[10];       // name of cursor mode
-  char  flags;          // MCF_flags above
-};
 
 // The editor-to-plugin interface
 class IAGSEditor {