engine_annotations.lua

--- @meta

--==============================================================================
-- UTILITY STRUCTURES
--==============================================================================

--- Windows POINT structure for 2D coordinates.
--- @class POINT
--- @field x number X coordinate
--- @field y number Y coordinate
POINT = {}

--- Creates a new POINT instance.
--- @return POINT
function POINT.new() end

--- Windows RECT structure representing a rectangle.
--- @class RECT
--- @field left number Left edge coordinate
--- @field top number Top edge coordinate
--- @field right number Right edge coordinate
--- @field bottom number Bottom edge coordinate
RECT = {}

--- Creates a new RECT instance.
--- @return RECT
function RECT.new() end

--- Windows SIZE structure for dimensions.
--- @class SIZE
--- @field cx number Width
--- @field cy number Height
SIZE = {}

--- Creates a new SIZE instance.
--- @return SIZE
function SIZE.new() end

--- Creates a COLORREF value from RGB components.
--- @param r number Red component (0-255)
--- @param g number Green component (0-255)
--- @param b number Blue component (0-255)
--- @return number COLORREF value
function RGB(r, g, b) end

--- @alias COLORREF number

--- Shape type constants for HitRegion.
--- @class ShapeEnum
--- @field Ellipse number Ellipse shape (0)
--- @field Rectangle number Rectangle shape (1)
Shape = {
    Ellipse = 0,
    Rectangle = 1
}

--==============================================================================
-- GAME ENGINE
--==============================================================================

--- @class GameEngine
--- Main game engine class for window management, rendering, and input handling.
local GameEngine = {}

--- Sets the window title.
--- @param title string
function GameEngine:SetTitle(title) end

--- Sets the window position.
--- @param left number
--- @param top number
function GameEngine:SetWindowPosition(left, top) end

--- Sets a custom window region.
--- @param regionPtr HitRegion
--- @return boolean
function GameEngine:SetWindowRegion(regionPtr) end

--- Sets the list of keys to track.
--- @param keyList string
function GameEngine:SetKeyList(keyList) end

--- Sets the frame rate.
--- @param frameRate number
function GameEngine:SetFrameRate(frameRate) end

--- Sets the window width.
--- @param width number
function GameEngine:SetWidth(width) end

--- Sets the window height.
--- @param height number
function GameEngine:SetHeight(height) end

--- Switches to fullscreen mode.
--- @return boolean
function GameEngine:GoFullscreen() end

--- Switches to windowed mode.
--- @return boolean
function GameEngine:GoWindowedMode() end

--- Shows or hides the mouse pointer.
--- @param show boolean
function GameEngine:ShowMousePointer(show) end

--- Quits the application.
function GameEngine:Quit() end

--- Checks if a custom window region is set.
--- @return boolean
function GameEngine:HasWindowRegion() end

--- Checks if the engine is in fullscreen mode.
--- @return boolean
function GameEngine:IsFullscreen() end

--- Checks if a key is currently pressed.
--- @param vKey number Virtual key code
--- @return boolean
function GameEngine:IsKeyDown(vKey) end

--- Shows a message box with a string message.
--- @param message string
--- @overload fun(self: GameEngine, value: number)
function GameEngine:MessageBox(message) end

--- Shows a continue/cancel message box.
--- @param message string
--- @return boolean true if continue, false if cancel
function GameEngine:MessageContinue(message) end

--- Calculates text dimensions.
--- @param text string
--- @param fontPtr Font
--- @return SIZE
--- @overload fun(self: GameEngine, text: string, fontPtr: Font, rect: RECT): SIZE
function GameEngine:CalculateTextDimensions(text, fontPtr) end

--- Sets the drawing color.
--- @param color COLORREF
function GameEngine:SetColor(color) end

--- Sets the font for drawing text.
--- @param fontPtr Font
function GameEngine:SetFont(fontPtr) end

--- Fills the entire window with the current color.
--- @param color COLORREF
--- @return boolean
function GameEngine:FillWindowRect(color) end

--- Draws a line.
--- @param x1 number
--- @param y1 number
--- @param x2 number
--- @param y2 number
--- @return boolean
function GameEngine:DrawLine(x1, y1, x2, y2) end

--- Draws a rectangle outline.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @return boolean
function GameEngine:DrawRect(left, top, right, bottom) end

--- Fills a rectangle.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @return boolean
--- @overload fun(self: GameEngine, left: number, top: number, right: number, bottom: number, opacity: number): boolean
function GameEngine:FillRect(left, top, right, bottom) end

--- Draws a rounded rectangle outline.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @param radius number
--- @return boolean
function GameEngine:DrawRoundRect(left, top, right, bottom, radius) end

--- Fills a rounded rectangle.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @param radius number
--- @return boolean
function GameEngine:FillRoundRect(left, top, right, bottom, radius) end

--- Draws an oval outline.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @return boolean
function GameEngine:DrawOval(left, top, right, bottom) end

--- Fills an oval.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @return boolean
--- @overload fun(self: GameEngine, left: number, top: number, right: number, bottom: number, opacity: number): boolean
function GameEngine:FillOval(left, top, right, bottom) end

--- Draws an arc.
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @param startDegree number
--- @param angle number
--- @return boolean
function GameEngine:DrawArc(left, top, right, bottom, startDegree, angle) end

--- Fills an arc (pie slice).
--- @param left number
--- @param top number
--- @param right number
--- @param bottom number
--- @param startDegree number
--- @param angle number
--- @return boolean
function GameEngine:FillArc(left, top, right, bottom, startDegree, angle) end

--- Draws text at the specified position.
--- @param text string
--- @param left number
--- @param top number
--- @return number Height of the drawn text
--- @overload fun(self: GameEngine, text: string, left: number, top: number, right: number, bottom: number): number
function GameEngine:DrawString(text, left, top) end

--- Draws a bitmap at the specified position.
--- @param bitmapPtr Bitmap
--- @param left number
--- @param top number
--- @return boolean
--- @overload fun(self: GameEngine, bitmapPtr: Bitmap, left: number, top: number, sourceRect: RECT): boolean
function GameEngine:DrawBitmap(bitmapPtr, left, top) end

--- Draws a polygon outline.
--- @param ptsArr POINT[]
--- @param count number
--- @return boolean
--- @overload fun(self: GameEngine, ptsArr: POINT[], count: number, close: boolean): boolean
function GameEngine:DrawPolygon(ptsArr, count) end

--- Fills a polygon.
--- @param ptsArr POINT[]
--- @param count number
--- @return boolean
--- @overload fun(self: GameEngine, ptsArr: POINT[], count: number, close: boolean): boolean
function GameEngine:FillPolygon(ptsArr, count) end

--- Gets the current drawing color.
--- @return COLORREF
function GameEngine:GetDrawColor() end

--- Triggers a repaint of the window.
--- @return boolean
function GameEngine:Repaint() end

--- Gets the window title.
--- @return string
function GameEngine:GetTitle() end

--- Gets the application instance handle.
--- @return userdata
function GameEngine:GetInstance() end

--- Gets the window handle.
--- @return userdata
function GameEngine:GetWindow() end

--- Gets the window width.
--- @return number
function GameEngine:GetWidth() end

--- Gets the window height.
--- @return number
function GameEngine:GetHeight() end

--- Gets the frame rate.
--- @return number
function GameEngine:GetFrameRate() end

--- Gets the frame delay in milliseconds.
--- @return number
function GameEngine:GetFrameDelay() end

--- Gets the window position.
--- @return POINT
function GameEngine:GetWindowPosition() end

--- Tabs to the next control.
function GameEngine:TabNext() end

--- Tabs to the previous control.
function GameEngine:TabPrevious() end

--==============================================================================
-- GRAPHICS AND MEDIA
--==============================================================================

--- @class Font
--- Font class for text rendering.
local Font = {}

--- Creates a new Font instance.
--- @param fontName string
--- @param bold boolean
--- @param italic boolean
--- @param underline boolean
--- @param size number
--- @return Font
function Font.new(fontName, bold, italic, underline, size) end

--- Gets the font handle.
--- @return userdata
function Font:GetHandle() end

--- @class HitRegion
--- Hit region for collision detection using Windows region API.
local HitRegion = {}

--- Creates a new HitRegion. Called as HitRegion(...) not HitRegion.new(...)
--- @param shape number Shape.Rectangle or Shape.Ellipse
--- @param left number Left coordinate
--- @param top number Top coordinate
--- @param right number Right coordinate
--- @param bottom number Bottom coordinate
--- @return HitRegion
--- @overload fun(points: POINT[]): HitRegion Create polygon region from points
--- @overload fun(bitmapPtr: Bitmap, cTransparent: COLORREF, cTolerance: COLORREF): HitRegion Create from bitmap
--- @overload fun(bitmapPtr: Bitmap, cTransparent: COLORREF): HitRegion Create from bitmap with transparency
--- @overload fun(bitmapPtr: Bitmap): HitRegion Create from bitmap (default magenta transparency)
function HitRegion(shape, left, top, right, bottom) end

--- Tests if a point is inside this region.
--- @param x number X coordinate
--- @param y number Y coordinate
--- @return boolean
--- @overload fun(self: HitRegion, regionPtr: HitRegion): boolean Test if another region overlaps
function HitRegion:HitTest(x, y) end

--- Moves the hit region by delta values.
--- @param deltaX number Horizontal displacement
--- @param deltaY number Vertical displacement
function HitRegion:Move(deltaX, deltaY) end

--- Gets the bounding rectangle of the region.
--- @return RECT
function HitRegion:GetBounds() end

--- Checks if the region was successfully created.
--- @return boolean
function HitRegion:Exists() end

--- Gets the Windows region handle.
--- @return userdata
function HitRegion:GetHandle() end

--- Tests collision with another region and returns the center point of the overlap.
--- @param regionPtr HitRegion
--- @return POINT Returns {x=-1000000, y=-1000000} if no collision, otherwise center of overlap
function HitRegion:CollisionTest(regionPtr) end

--- @class Audio : Caller
--- Audio playback class for sound effects and music.
local Audio = {}

--- Creates a new Audio instance.
--- @param filename string Path to audio file
--- @return Audio
function Audio.new(filename) end

--- Updates audio state (call each frame for proper playback).
function Audio:Tick() end

--- Plays the audio from the beginning.
--- @overload fun(self: Audio, msecStart: number) Play from specific position
--- @overload fun(self: Audio, msecStart: number, msecStop: number) Play a specific range
function Audio:Play() end

--- Pauses the audio playback.
function Audio:Pause() end

--- Stops the audio playback.
function Audio:Stop() end

--- Sets the volume level.
--- @param volume number Volume level (0-1000)
function Audio:SetVolume(volume) end

--- Sets whether audio should repeat.
--- @param shouldRepeat boolean
function Audio:SetRepeat(shouldRepeat) end

--- Gets the filename.
--- @return string
function Audio:GetName() end

--- Gets the audio alias used internally.
--- @return string
function Audio:GetAlias() end

--- Gets the duration in milliseconds.
--- @return number
function Audio:GetDuration() end

--- Checks if audio is currently playing.
--- @return boolean
function Audio:IsPlaying() end

--- Checks if audio is paused.
--- @return boolean
function Audio:IsPaused() end

--- Checks if repeat mode is enabled.
--- @return boolean
function Audio:GetRepeat() end

--- Checks if the audio file exists and loaded successfully.
--- @return boolean
function Audio:Exists() end

--- Gets the current volume level.
--- @return number
function Audio:GetVolume() end

--- Gets the type identifier string.
--- @return string
function Audio:GetType() end

--- @class Bitmap
--- Bitmap image class for loading and drawing images.
local Bitmap = {}

--- Creates a new Bitmap instance. Called as Bitmap(...) not Bitmap.new(...)
--- @param filename string Path to image file
--- @param createAlphaChannel? boolean Whether to create alpha channel (default false)
--- @return Bitmap
--- @overload fun(filename: string): Bitmap
function Bitmap(filename, createAlphaChannel) end

--- Sets the transparency color (pixels of this color will be transparent).
--- @param color COLORREF
function Bitmap:SetTransparencyColor(color) end

--- Sets the overall opacity of the bitmap.
--- @param opacity number Opacity level (0-255)
function Bitmap:SetOpacity(opacity) end

--- Checks if the bitmap loaded successfully.
--- @return boolean
function Bitmap:Exists() end

--- Gets the bitmap width in pixels.
--- @return number
function Bitmap:GetWidth() end

--- Gets the bitmap height in pixels.
--- @return number
function Bitmap:GetHeight() end

--- Gets the transparency color.
--- @return COLORREF
function Bitmap:GetTransparencyColor() end

--- Gets the current opacity level.
--- @return number
function Bitmap:GetOpacity() end

--- Checks if bitmap has an alpha channel.
--- @return boolean
function Bitmap:HasAlphaChannel() end

--- Saves the bitmap to a file.
--- @param filename string
--- @return boolean
function Bitmap:SaveToFile(filename) end

--- Gets the bitmap handle.
--- @return userdata
function Bitmap:GetHandle() end

--==============================================================================
-- UI CONTROLS AND EVENTS
--==============================================================================

--- @class Callable
--- Base class for objects that can receive callbacks.
local Callable = {}

--- Called when an action is triggered.
--- @param callerPtr Caller
function Callable:CallAction(callerPtr) end

--- @class Caller
--- Base class for objects that can trigger CallAction events (Timer, Button, TextBox, Audio).
local Caller = {}

--- Adds an action listener.
--- @param targetPtr Callable
--- @return boolean
function Caller:AddActionListener(targetPtr) end

--- Removes an action listener.
--- @param targetPtr Callable
--- @return boolean
function Caller:RemoveActionListener(targetPtr) end

--- Gets the type identifier.
--- @return string
function Caller:GetType() end

--- @class Timer : Caller
--- Timer class for periodic or one-shot events.
local Timer = {}

--- Creates a new Timer instance.
--- @param msec number Delay in milliseconds
--- @param targetPtr Callable Callback object
--- @param repeat boolean true for repeating timer, false for one-shot
--- @return Timer
function Timer.new(msec, targetPtr, repeat) end

--- Starts the timer.
function Timer:Start() end

--- Stops the timer.
function Timer:Stop() end

--- Sets the timer delay in milliseconds.
--- @param msec number
function Timer:SetDelay(msec) end

--- Sets whether the timer should repeat.
--- @param repeat boolean
function Timer:SetRepeat(repeat) end

--- Checks if the timer is currently running.
--- @return boolean
function Timer:IsRunning() end

--- Gets the delay in milliseconds.
--- @return number
function Timer:GetDelay() end

--- Gets the type identifier.
--- @return string
function Timer:GetType() end

--- @class Button : Caller
--- Button UI control for clickable buttons.
local Button = {}

--- Creates a new Button instance.
--- @param label string Button text
--- @return Button
function Button.new(label) end

--- Sets the button bounds (position and size).
--- @param left number Left edge
--- @param top number Top edge
--- @param right number Right edge
--- @param bottom number Bottom edge
function Button:SetBounds(left, top, right, bottom) end

--- Sets the button text.
--- @param text string
function Button:SetText(text) end

--- Sets the button font.
--- @param fontName string
--- @param bold boolean
--- @param italic boolean
--- @param underline boolean
--- @param size number
function Button:SetFont(fontName, bold, italic, underline, size) end

--- Enables or disables the button.
--- @param enable boolean
function Button:SetEnabled(enable) end

--- Shows the button and registers action listener.
function Button:Show() end

--- Hides the button and unregisters action listener.
function Button:Hide() end

--- Gets the button bounds.
--- @return RECT
function Button:GetBounds() end

--- Gets the button text.
--- @return string
function Button:GetText() end

--- Gets the type identifier.
--- @return string
function Button:GetType() end

--- @class TextBox : Caller
--- TextBox UI control for text input.
local TextBox = {}

--- Creates a new TextBox instance.
--- @param text string Initial text
--- @return TextBox
function TextBox.new(text) end

--- Sets the textbox bounds (position and size).
--- @param left number Left edge
--- @param top number Top edge
--- @param right number Right edge
--- @param bottom number Bottom edge
function TextBox:SetBounds(left, top, right, bottom) end

--- Sets the textbox text.
--- @param text string
function TextBox:SetText(text) end

--- Sets the textbox font.
--- @param fontName string
--- @param bold boolean
--- @param italic boolean
--- @param underline boolean
--- @param size number
function TextBox:SetFont(fontName, bold, italic, underline, size) end

--- Sets the background color.
--- @param color COLORREF
function TextBox:SetBackcolor(color) end

--- Sets the foreground (text) color.
--- @param color COLORREF
function TextBox:SetForecolor(color) end

--- Enables or disables the textbox.
--- @param enable boolean
function TextBox:SetEnabled(enable) end

--- Shows the textbox and registers action listener.
function TextBox:Show() end

--- Hides the textbox and unregisters action listener.
function TextBox:Hide() end

--- Gets the textbox bounds.
--- @return RECT
function TextBox:GetBounds() end

--- Gets the textbox text.
--- @return string
function TextBox:GetText() end

--- Gets the foreground color.
--- @return COLORREF
function TextBox:GetForecolor() end

--- Gets the background color.
--- @return COLORREF
function TextBox:GetBackcolor() end

--- Gets the background brush handle.
--- @return userdata
function TextBox:GetBackcolorBrush() end

--- Gets the type identifier.
--- @return string
function TextBox:GetType() end

--==============================================================================
-- GLOBAL VARIABLES
--==============================================================================

--- Global game engine instance.
--- @type GameEngine
GAME_ENGINE = {}

--==============================================================================
-- VIRTUAL KEY CODES
--==============================================================================

--- @type number Left arrow key
LEFT = 0
--- @type number Right arrow key
RIGHT = 0
--- @type number Up arrow key
UP = 0
--- @type number Down arrow key
DOWN = 0
--- @type number Space bar
SPACE = 0
--- @type number Enter/Return key
RETURN = 0
--- @type number Escape key
ESCAPE = 0
--- @type number Shift key
SHIFT = 0
--- @type number Control key
CONTROL = 0
--- @type number Tab key
TAB = 0

-- Letter Keys (A-Z)
--- @type number
A = 0
--- @type number
B = 0
--- @type number
C = 0
--- @type number
D = 0
--- @type number
E = 0
--- @type number
F = 0
--- @type number
G = 0
--- @type number
H = 0
--- @type number
I = 0
--- @type number
J = 0
--- @type number
K = 0
--- @type number
L = 0
--- @type number
M = 0
--- @type number
N = 0
--- @type number
O = 0
--- @type number
P = 0
--- @type number
Q = 0
--- @type number
R = 0
--- @type number
S = 0
--- @type number
T = 0
--- @type number
U = 0
--- @type number
V = 0
--- @type number
W = 0
--- @type number
X = 0
--- @type number
Y = 0
--- @type number
Z = 0

-- Number Keys (0-9)
--- @type number
_0 = 0
--- @type number
_1 = 0
--- @type number
_2 = 0
--- @type number
_3 = 0
--- @type number
_4 = 0
--- @type number
_5 = 0
--- @type number
_6 = 0
--- @type number
_7 = 0
--- @type number
_8 = 0
--- @type number
_9 = 0