AGS clean refresh to OO *style*

[Ryan Timothy B]

I would love to see AGS's default functions and variables being changed to a more solid OO method. Where things are more conformed and easier to remember and find. It ultimately "shouldn't" break backwards compatibility, still having access to both new and old - only these ones being in the autocomplete list and manual.

Whether the public agrees with this or not - I'm posting it anyway. If you don't agree with any of the name changes or I've missed something - feel free to respond.


List of new OO functions and variables (I accidentally made all variables first letter lower case - which isn't uniform to AGS, I'll edit later):

Code: ags

Background.ColorDepth()
Background.GetDrawingSurface()
Background.frame  <-- int
Background.Animate(Direction, int delay)
Background.StopAnimating()
Background.IsAnimating()

ROOM.Visited()
ROOM.Reset()

ROOM.width
ROOM.height

ROOM.WalkableArea.GetScalingAt(int x, int y)
ROOM.WalkableArea.GetScalingAtScreen(int x, int y)
ROOM.WalkableArea.SetAreaScaling(int areaID, int min, int max)
ROOM.WalkableArea.GetAreaAt(int x, int y)
ROOM.WalkableArea.GetAreaAtScreen(int x, int y)
ROOM.WalkableArea.DisableArea(int areaID)
ROOM.WalkableArea.EnableArea(int areaID)
ROOM.WalkableArea.IsAreaActive(int areaID)

ROOM.Layer.SetBaseline(int layerID, int baselineY)

ROOM.Edge.Bottom.y
ROOM.Edge.Left.x
ROOM.Edge.Right.x 
ROOM.Edge.Top.y 
ROOM.Edge.DisableAll()
ROOM.Edge.EnableAll()
ROOM.Edge.Bottom.active
ROOM.Edge.Left.active
ROOM.Edge.Right.active
ROOM.Edge.Top.active 

Screen.FadeIn(int speed)
Screen.FadeOut(int speed)
Screen.Flip(FlipDirection)  <-- new built-in Enum - instead of int
Screen.SetFadeColor(int red, int green, int blue)
Screen.ResetFadeColor()
Screen.SetTransition(TransitionStyle)
Screen.SetNextTransition(TransitionStyle)
Screen.Shake(int delay, int distance, int duration, BlockingStyle)
Screen.StopShake()
Screen.Tint(int red, int green, int blue, int transparency)  <-- added parameters
Screen.RemoveTint()

Viewport.x
Viewport.y
Viewport.Set(int x, int y)
Viewport.Get()  <-- Returns Vector2 of X and Y
Viewport.Release()
Viewport.FollowCharacter(Character character)
Viewport.Move(int x, int y, int speed, BlockingStyle)
Viewport.width
Viewport.height

Character.RemoveInventory(InventoryItem *item)
Character.IsInteractionAvailable(CursorMode)

Object.IsInteractionAvailable(CursorMode)

Hotspot.IsInteractionAvailable(CursorMode)

Cutscene.Start(CutsceneSkipType)
Cutscene.End()
Cutscene.Active()
Cutscene.Skipping()

Key.IsButtonDown(eKeyCode)  <-- to match Mouse.IsButtonDown

Game.IsInteractionAvailableAtScreen(int x, int y, int mode)
Game.SkipCharacterTravelTime(Character character)
Game.SetSpeechSkipAction(SpeechSkip)
Game.IsPaused()
Game.score
Game.GetLocationTypeAt(int x, int y)
Game.GetLocationTypeAtScreen(int x, int y)
Game.GetLocationNameAt(int x, int y)
Game.GetLocationNameAtScreen(int x, int y)
Game.gameSpeed

System.windowHeight
System.windowWidth

Font.GetTextWidth(String text, FontType)
Font.GetTextHeight(String text, FrontType, int width)

Click to see Overview (what is being replaced with what):

Spoiler

=== ROOMS ===================================
Background:
  ColorDepth
    ^  Change to: Background.ColorDepth()
  GetDrawingSurfaceForBackground(..)
    ^  Change to: Background.GetDrawingSurface()
  GetBackgroundFrame(..)  &  SetBackgroundFrame(..)
    ^  Change to: Background.frame  <-- int
  Add:
       Background.Animate(Direction, int delay)
       Background.StopAnimating()
       Background.IsAnimating()

  HasPlayerBeenInRoom(..)
    ^  Change to: ROOM.Visited()  <-- name may be misleading
  ResetRoom(..)
    ^  Change to: ROOM.Reset()
  Add:
         ROOM.width
         ROOM.height

Walkable Area:
  GetScalingAt(..)
    ^  Change to: ROOM.WalkableArea.GetScalingAt(int x, int y)
    ^  Add: ROOM.WalkableArea.GetScalingAtScreen(int x, int y)
  SetAreaScaling(..)
    ^  Change to: ROOM.WalkableArea.SetAreaScaling(int areaID, int min, int max)
  GetWalkableAreaAt(..)
    ^  Change to: ROOM.WalkableArea.GetAreaAt(int x, int y)
    ^  Add: ROOM.WalkableArea.GetAreaAtScreen(int x, int y)
  RemoveWalkableArea(..)
    ^ Change to: ROOM.WalkableArea.DisableArea(int areaID)
  RestoreWalkableArea(..)
    ^ Change to: ROOM.WalkableArea.EnableArea(int areaID)
  Add:
       ROOM.WalkableArea.IsAreaActive(int areaID)

Walk-behind Area (changed to: Layer):
  SetWalkBehindBase(..)
    ^  Change to: ROOM.Layer.SetBaseline(int layerID, int baselineY)

Edge (this one is overkill on the OO - need suggestions):
  BottomEdge > Add: ROOM.Edge.Bottom.y  <-- int
  LeftEdge   > Add: ROOM.Edge.Left.x    <-- int
  RightEdge  > Add: ROOM.Edge.Right.x   <-- int
  TopEdge    > Add: ROOM.Edge.Top.y     <-- int
  Add:
       ROOM.Edge.DisableAll()
       ROOM.Edge.EnableAll()
       ROOM.Edge.Bottom.active <-- Boolean
       ROOM.Edge.Left.active   <-- Boolean
       ROOM.Edge.Right.active  <-- Boolean
       ROOM.Edge.Top.active    <-- Boolean



=== SCREEN ==================================
  FadeIn(..)
    ^ Change to: Screen.FadeIn(int speed)
  FadeOut(..)
    ^ Change to: Screen.FadeOut(int speed)
  FlipScreen(..)
    ^ Change to: Screen.Flip(FlipDirection)  <-- new built-in Enum - instead of int
  SetFadeColor(..)
    ^ Change to: Screen.SetFadeColor(int red, int green, int blue)
    Add: Screen.ResetFadeColor()
  SetScreenTransition(..)
    ^ Change to: Screen.SetTransition(TransitionStyle)
  SetNextScreenTransition(..)
    ^ Change to: Screen.SetNextTransition(TransitionStyle)
  ShakeScreen(..) & ShakeScreenBackground(..)
    ^ Change to: Screen.Shake(int delay, int distance, int duration, BlockingStyle)  <-- changed parameters
    Add: Screen.StopShake()
  TintScreen(..)
    ^ Change to: Screen.Tint(int red, int green, int blue, int transparency)  <-- added parameters
    Add: Screen.RemoveTint()

Viewport
  GetViewportX()
    ^ Change to: Viewport.x   <-- int
  GetViewportY()
    ^ Change to: Viewport.y   <-- int
  SetViewport(..)
    ^ Change to: Viewport.Set(int x, int y)
  Add:
       Viewport.Get()  <-- Returns Vector2 of X and Y
 
  ReleaseViewport()
    ^  Change to:  Viewport.Release()
  Add:
       Viewport.FollowCharacter(Character character)  <-- releases viewport if character leaves room
       Viewport.Move(int x, int y, int speed, BlockingStyle)
       Viewport.width
       Viewport.height



=== CHARACTER ===============================
  Character.LoseInventory(..)
    ^ Change to: Character.RemoveInventory(InventoryItem *item) <-- keeping opposite of: AddInventory
  Add:
       Character.IsInteractionAvailable(CursorMode)

=== OBJECT ==================================
  Add:
       Object.IsInteractionAvailable(CursorMode)

=== HOTSPOT =================================
  Add:
       Hotspot.IsInteractionAvailable(CursorMode)



=== CUTSCENE ================================
  StartCutscene(..)
    ^ Change to: Cutscene.Start(CutsceneSkipType)
  EndCutscene(..)
    ^ Change to: Cutscene.End()
  Game.InSkippableCutscene
    ^ Change to: Cutscene.Active()  <-- possibly misleading
  Game.SkippingCutscene
    ^ Change to: Cutscene.Skipping()



=== KEY =====================================
  IsKeyPressed(..)
    ^ Change to: Key.IsButtonDown(eKeyCode)  <-- to match Mouse.IsButtonDown



=== GAME ====================================
  IsInteractionAvailable(..)
    ^ Change to: Game.IsInteractionAvailableAtScreen(int x, int y, int mode)
  SkipUntilCharacterStops(..)
    ^ Change to: Game.SkipCharacterTravelTime(Character character)  <-- changed parameters
  SetSkipSpeech(..)
    ^ Change to: Game.SetSpeechSkipAction(SpeechSkip)  <-- new built-in enum - instead of int
  IsGamePaused ()
    ^ Change to: Game.IsPaused()
  GiveScore(..)
    ^ Change to: Game.score  <-- int
  GetLocationType(..)
    ^ Change to: Game.GetLocationTypeAt(int x, int y)
      Add: Game.GetLocationTypeAtScreen(int x, int y)
  Game.GetLocationName(..)
    ^ Change to: Game.GetLocationNameAt(int x, int y)
      Add: Game.GetLocationNameAtScreen(int x, int y)
  GetGameSpeed()  &  SetGameSpeed()
    ^ Change to: Game.fps  <-- int


 
=== SYSTEM ==================================
  System.ScreenHeight
    ^ Change to: System.windowHeight
  System.ScreenWidth
    ^ Change to: System.windowWidth



=== TEXT ====================================
  GetTextWidth(..)
    ^ Change to: Font.GetTextWidth(String text, FontType)
  GetTextHeight(..)
    ^ Change to: Font.GetTextHeight(String text, FrontType, int width)



=== SRIPTING ================================
  While in a "global" script you must refer to the room by name. EG:
    rBeach.Background.Frame = 2;
  OR adding a "currentRoom", equivalent to "player":
    currentRoom.Background.Frame = 2;





=== OTHERS THAT NEED ATTENTION ==============
IsSpeechVoxAvailable()
IsTranslationAvailable()
IsTimerExpired(..)
SetTimer(..)
IsInterfaceEnabled()
DisableInterface()
EnableInterface()
GetGameOption()
SetGameOption()
DisableGroundLevelAreas(..)
EnableGroundLevelAreas(..)
AreThingsOverlapping()
GetRoomProperty()
GetTextProperty()
ChangeRoomAutoPosition()

[close]

I'm sure there's plenty more - these are just the ones that I could remember or saw while quickly scrolling through manual

[Calin Leafshade]

I like the idea but AGS script itself does not allow for a truly OOP style so your changes are just syntactic rather than organisational.

[Crimson Wizard]

I like the idea but AGS script itself does not allow for a truly OOP style

Why?
Aren't there object-oriented character, object etc functions? Functions for custom struct objects?

[Calin Leafshade]

- Can't pass references to user structures
- Extremely limited polymorphism (no overriding, limited subclassing)
- Limited encapsulation

EDIT: Actually encapsulation is possible but its wordy.

[Ryan Timothy B]

I like the idea but AGS script itself does not allow for a truly OOP style so your changes are just syntactic rather than organisational.

That's all I'm really going for - unless AGS script were to be removed for C# or Java (I prefer C# - and would even pay someone a little something of a bonus for a working C# version, perhaps something like Eclipse as the editor within AGS?).

And I mainly just meant organizational for the individual programmers using AGS.

[Monsieur OUXX]

Here we go again.
We have so many code geniuses developing AGS. If only they'd get started, it would be done in a month I'm sure! 

[Ryan Timothy B]

Here we go again.
We have so many code geniuses developing AGS. If only they'd get started, it would be done in a month I'm sure! 

That was quite a bit sarcastic for no reason.

I was only putting the record out there that all these functions, in a non OO style, really don't fit with AGS. They're the things I constantly stumble on while programming - forgetting if this is the one that isn't in a OO style or the others.

Drop the attitude next time.

[AGA]

I think his point was more that this has been raised before, and the discussion went around in circles.  Someone needs to actually do something, rather than another discussion starting!

[Calin Leafshade]

That's how i read it too. I dont think frenchie was being overly sarcastic.

@Ryan

Implementing your changes would actually be astonishingly easy. You just need to edit the agsdefs file which is just an AGS header and then edit the section in the engine where those functions are linked. You aren't changing any functionality you're just rearranging the syntax. Not sure I think you *should* do that but you could if you wanted.

[Ryan Timothy B]

I likely over read the tone.

I thought it was "Here we go again, we have someone making *more* suggestions". Unless he was referring to the part of dropping AGS Script for C# (which I agree is one hell of an undertaking - but probably much less work than reworking what's currently there to be *exactly* like C#; which has actually been suggested in the past by numerous people). I only mentioned it because it's something I would ultimately like to see done. I don't expect anyone to do it - but it would be surprisingly awesome.

And yes, I hadn't planned on doing these suggestions myself which is why I posted here. I don't have access to the wonderful version Crimson and the others have been working with, and I figured something like this was relatively easy as it was just a syntax thing - not true OO. I suppose I should've put "AGS clean refresh to OO *style*" in the subject.

[Crimson Wizard]

Some time ago I suggested that some kind of group be formed in AGS community to define AGS scripting standard (functions, etc).
I really hoped some of the older members (I mean, those who script a lot) would do that, but it seems no one wanted to (or maybe they just did not read my post ).
Wyz made a good point there, that script changes (including adding new functions) should be treated with care, otherwise script library may become cluttered and cause confusion to people.


Regarding changing script to something, there was already C# plugins few years ago, but I have no idea how much they are useable:
http://www.adventuregamestudio.co.uk/forums/index.php?topic=41465.0
http://www.adventuregamestudio.co.uk/forums/index.php?topic=41635.0

I am not sure you can make a plugin that will bind Java to C++ engine. for C# one may use C++/CLR wrapper, but does Java allow something like that? Unless you will work with it via pipe or something.
Also, now when we have ports, one should at least take other platforms into consideration.

[Phemar]

I like all these ideas and am in full support. Even if it's not true OO programming, consistency in commands is key to hassle-free scripting and this would make life a lot easier than continually consulting the manual and trying to remember which commands are called on an object and which commands aren't.

[SSH]

<unhelpful joke>
We don't just want OO style, we want OO pa gangnam style!

[selmiak]