Category: Input

Syntax:

inpUnclipMouse:Void()

Void

Removes mouse cursor confinement (allows cursor to move freely across desktop).

Takes no parameters.

Returns nothing.

View detailed documentation online

; Pause menu toggle - clip/unclip with menu state
If inpIsKeyHit(VKEY_ESCAPE) Then
    paused% = Not paused%

    If paused% Then
        ; Entering pause menu
        inpUnclipMouse()          ; Free cursor for menu
        inpSetMouseVisible(True)  ; Show cursor
    Else
        ; Resuming gameplay
        inpClipMouseToWindow()    ; Re-confine cursor
        inpSetMouseVisible(False) ; Hide cursor
    EndIf
EndIf

; Game shutdown - always unclip before exit
Function Shutdown()
    inpUnclipMouse()  ; Restore normal cursor behavior
    inpSetMouseVisible(True)  ; Ensure cursor visible
    b2dEnd()
    End
EndFunction

; Window focus management
Function OnWindowDeactivate()
    ; User Alt-Tabbed or clicked outside window
    inpUnclipMouse()  ; Free cursor immediately
    gamePaused% = True
EndFunction

Function OnWindowActivate()
    ; User clicked back into window
    If Not menuActive% Then
        inpClipMouseToWindow()  ; Re-confine if in gameplay
        gamePaused% = False
    EndIf
EndFunction

; Debug toggle for development
If inpIsKeyHit(VKEY_F12) Then
    debugMode% = Not debugMode%

    If debugMode% Then
        inpUnclipMouse()          ; Free cursor for debugger access
        inpSetMouseVisible(True)  ; Show cursor
        Print "Debug mode: cursor free"
    Else
        inpClipMouseToWindow()    ; Re-confine for gameplay testing
        inpSetMouseVisible(False)  ; Hide cursor
        Print "Debug mode: cursor clipped"
    EndIf
EndIf

; Menu system with proper cursor management
Function ShowMainMenu()
    inpUnclipMouse()          ; Free cursor
    inpSetMouseVisible(True)  ; Show cursor
    menuActive% = True
EndFunction

Function HideMainMenu()
    inpClipMouseToWindow()    ; Confine cursor
    inpSetMouseVisible(False) ; Hide cursor
    menuActive% = False
EndFunction

; Game state management with cleanup
Function MainLoop()
    While running%
        sysUpdateEvents()

        If inpIsKeyHit(VKEY_ESCAPE) Then
            TogglePauseMenu()
        EndIf

        If Not paused% Then
            UpdateGameplay()
        Else
            UpdateMenu()
        EndIf

        Render()
    Wend

    ; Cleanup - always unclip on exit
    inpUnclipMouse()
    inpSetMouseVisible(True)
EndFunction

; Cutscene handling (optional unclip during non-interactive scenes)
Function StartCutscene()
    cutscenePlaying% = True
    inpUnclipMouse()          ; Allow free cursor (or keep clipped, depends on design)
    inpSetMouseVisible(False) ; Cursor still hidden but can move freely
EndFunction

Function EndCutscene()
    cutscenePlaying% = False
    inpClipMouseToWindow()    ; Re-confine for gameplay
    inpSetMouseVisible(False) ; Keep hidden
EndFunction

; Error-safe game loop with guaranteed cleanup
Function SafeGameLoop()
    Try
        inpClipMouseToWindow()
        inpSetMouseVisible(False)

        While running%
            ; ... game logic ...
        Wend
    Finally
        ; Always execute cleanup even on error/crash
        inpUnclipMouse()
        inpSetMouseVisible(True)
    EndTry
EndFunction
```


[meta]
since = "1.0"
status = "stable"

BambooBasic © 2026 Michael Denathorn