Merge pull request #750 from JiepengTan/pr_coro_env_check

Feat: Enhance SPX coroutine detection

Author: JiepengTan

go.mod

@@ -9,7 +9,10 @@ require (
 	golang.org/x/mobile v0.0.0-20220518205345-8578da9835fd
 )
 
-require golang.org/x/image v0.23.0 // indirect
+require (
+	github.com/petermattis/goid v0.0.0-20250721140440-ea1c0173183e // indirect
+	golang.org/x/image v0.23.0 // indirect
+)
 
 replace (
 	golang.org/x/image => golang.org/x/image v0.0.0-20210628002857-a66eb6448b8d

go.sum

@@ -1,6 +1,8 @@
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
 github.com/h2non/filetype v1.1.3 h1:FKkx9QbD7HR/zjK1Ia5XiBsq9zdLi5Kf3zGyFTAFkGg=
 github.com/h2non/filetype v1.1.3/go.mod h1:319b3zT68BvV+WRj7cwy856M2ehB3HqNOt6sy1HndBY=
+github.com/petermattis/goid v0.0.0-20250721140440-ea1c0173183e h1:D0bJD+4O3G4izvrQUmzCL80zazlN7EwJ0PPDhpJWC/I=
+github.com/petermattis/goid v0.0.0-20250721140440-ea1c0173183e/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/realdream-ai/mathf v0.0.0-20250513071532-e55e1277a8c5 h1:KuC3mEHh8NPOaOR0acOW+6ISKL4S9iY3n102KE/tst0=

internal/coroutine/coro.go

@@ -14,6 +14,7 @@ import (
 	"github.com/goplus/spx/v2/internal/debug"
 	"github.com/goplus/spx/v2/internal/engine/platform"
 	"github.com/goplus/spx/v2/internal/time"
+	"github.com/petermattis/goid"
 )
 
 var (
@@ -85,6 +86,9 @@ type Coroutines struct {
 	waitMutex sync.Mutex
 	waitCond  sync.Cond
 	debug     bool
+	
+	// goroutineIDs tracks all goroutine IDs created by CreateAndStart
+	goroutineIDs sync.Map // map[int64]bool
 }
 
 const (
@@ -195,6 +199,10 @@ func (p *Coroutines) CreateAndStart(start bool, tobj ThreadObj, fn func(me Threa
 
 	id.cond = sync.NewCond(&id.mutex) // Initialize the thread's condition variable
 	go func() {
+		// Track this goroutine ID
+		gid := goid.Get()
+		p.goroutineIDs.Store(gid, true)
+		
 		p.sema.Lock()
 		p.setCurrent(id)
 		defer func() {
@@ -203,6 +211,10 @@ func (p *Coroutines) CreateAndStart(start bool, tobj ThreadObj, fn func(me Threa
 			p.mutex.Unlock()
 			p.setWaitStatus(id, waitStatusDelete)
 			p.sema.Unlock()
+			
+			// Remove goroutine ID from tracking
+			p.goroutineIDs.Delete(gid)
+			
 			if e := recover(); e != nil {
 				if e != ErrAbortThread {
 					if p.onPanic != nil {
@@ -555,3 +567,11 @@ func (p *Coroutines) Update() {
 	lastDebugUpdateStats = stats
 
 }
+
+// IsInCoroutine checks if the current execution environment is within
+// a coroutine created by (*Coroutines) CreateAndStart.
+func (p *Coroutines) IsInCoroutine() bool {
+	currentGID := goid.Get()
+	_, exists := p.goroutineIDs.Load(currentGID)
+	return exists
+}

internal/engine/coro.go

@@ -19,8 +19,18 @@ func GetGame() any {
 	return pgame
 }
 
-func IsSpxEnv() bool {
-	return GetGame() != nil
+func IsInCoroutine() bool {
+	if gco == nil {
+		return false
+	}
+	return gco.IsInCoroutine()
+}
+
+func GetCoroutineOwner() any {
+	if IsInCoroutine() {
+		return gco.Current().Obj
+	}
+	return nil
 }
 
 func SetCoroutines(co *coroutine.Coroutines) {

pkg/spx/api.go

@@ -7,20 +7,63 @@ import (
 	"github.com/goplus/spx/v2/internal/engine"
 )
 
-// HasInit checks if the SPX engine has been initialized.
-func IsSpxEnv() bool {
-	return engine.IsSpxEnv()
+func isSpxEnv() bool {
+	return engine.GetGame() != nil
 }
 
-// Executes the given function in a native Go goroutine from the current SPX coroutine context and waits for completion.
-// While waiting, it yields control via waitNextFrame to avoid blocking the SPX main thread.
-// Use this when you need to run potentially blocking Go operations (e.g., network requests, file I/O) from within SPX.
-func RunGoFromSpx(fn func()) {
+// IsInCoroutine checks whether the current execution context is within an SPX coroutine.
+// Returns true if running inside an SPX coroutine, false if running in a regular Go goroutine
+// or the main thread.
+//
+// This function is useful for determining the appropriate execution strategy when your code
+// needs to work in both SPX coroutine and regular Go contexts.
+//
+// Example:
+//
+//	if spx.IsInCoroutine() {
+//	    // Use SPX-specific functions like Wait() or WaitNextFrame()
+//	    spx.Wait(1.0)
+//	} else {
+//	    // Use regular Go functions
+//	    time.Sleep(time.Second)
+//	}
+func IsInCoroutine() bool {
+	return engine.IsInCoroutine()
+}
+
+// ExecuteNative executes the given function in a native Go goroutine and waits for its completion.
+// While waiting, if it is in spx corotine, it yields control via WaitNextFrame to avoid blocking
+// the SPX main thread.
+//
+// This function is essential when you need to perform blocking Go operations (such as network requests,
+// file I/O, or system calls) from within an SPX coroutine without freezing the game engine.
+//
+// If called from outside an SPX coroutine context, the function executes synchronously.
+//
+// Example:
+//
+//	spx.ExecuteNative(func() {
+//	    // Perform blocking network request
+//	    resp, err := http.Get("https://api.example.com/data")
+//	    if err != nil {
+//	        log.Printf("Error: %v", err)
+//	        return
+//	    }
+//	    defer resp.Body.Close()
+//	    // Process response...
+//	})
+func ExecuteNative(fn func(owner any)) {
+	// if not in spx coro, just run it
+	if !engine.IsInCoroutine() {
+		fn(nil)
+		return
+	}
+	owner := engine.GetCoroutineOwner()
 	done := &atomic.Bool{}
-	// Run the actual logic in a go routine to avoid blocking
+	// Execute the actual logic in a go routine to avoid blocking
 	go func() {
 		defer done.Store(true)
-		fn()
+		fn(owner)
 	}()
 	// Wait for completion while yielding control to SPX
 	for !done.Load() {
@@ -31,11 +74,22 @@ func RunGoFromSpx(fn func()) {
 // Executes the given function in an SPX coroutine from the current Go goroutine context and waits for completion.
 // This function blocks until fn finishes execution.
 // Use this when you need to synchronously wait for the SPX coroutine to complete.
-func RunSpxFromGo(fn func()) {
+//
+// Parameters:
+//
+//	owner - The SPX coroutine owner. When the owner is destroyed, all coroutines created by this owner will be properly stopped.
+//	fn - The function to execute in the coroutine context.
+func Execute(owner any, fn func(owner any)) {
+	// in spx coro, just run it
+	if engine.IsInCoroutine() {
+		fn(owner)
+		return
+	}
+
 	done := make(chan struct{}, 1)
-	StartSpxCoro(func() {
+	Go(owner, func(any) {
 		defer close(done)
-		fn()
+		fn(owner)
 	})
 	<-done
 }
@@ -44,6 +98,12 @@ func RunSpxFromGo(fn func()) {
 // This is useful for running multiple operations in parallel without blocking
 // the main execution flow.
 //
+// Parameters:
+//
+//	owner - The SPX coroutine owner. When the owner is destroyed, all coroutines created by this owner will be properly stopped.
+//	        If nil, the current coroutine's owner or the game instance will be used as the owner.
+//	fn - The function to execute in the coroutine context.
+//
 // IMPORTANT: For long-running tasks, you MUST call Wait() or WaitNextFrame()
 // periodically to yield control back to the engine. Without these calls,
 // the main thread will wait indefinitely for the coroutine to complete,
@@ -56,7 +116,7 @@ func RunSpxFromGo(fn func()) {
 //
 //	done := false
 //	// ... do something
-//	spx.GoAsync(func() {
+//	spx.Go(owner, func(owner any) {
 //	    // ... do something
 //	    for !done {
 //	        // Do some work here
@@ -66,17 +126,24 @@ func RunSpxFromGo(fn func()) {
 //
 // Example of simple delayed execution:
 //
-//	spx.GoAsync(func() {
+//	spx.Go(owner, func(owner any) {
 //	    spx.Wait(2.0)
 //	    fmt.Println("Hello after 2 seconds")
 //	})
-func StartSpxCoro(fn func()) {
-	if IsSpxEnv() {
-		engine.Go(engine.GetGame(), func() {
-			fn()
+func Go(owner any, fn func(owner any)) {
+	if isSpxEnv() {
+		if owner == nil {
+			if IsInCoroutine() {
+				owner = engine.GetCoroutineOwner()
+			} else {
+				owner = engine.GetGame()
+			}
+		}
+		engine.Go(owner, func() {
+			fn(owner)
 		})
 	} else {
-		go fn()
+		go fn(owner)
 	}
 }
 
@@ -99,7 +166,7 @@ func StartSpxCoro(fn func()) {
 //
 //	actualTime := spx.Wait(1.5) // Wait for 1.5 seconds
 func Wait(secs float64) float64 {
-	if IsSpxEnv() {
+	if engine.IsInCoroutine() {
 		return engine.Wait(secs)
 	} else {
 		// Fallback to a regular wait
@@ -129,7 +196,7 @@ func Wait(secs float64) float64 {
 //	    }
 //	}
 func WaitNextFrame() float64 {
-	if IsSpxEnv() {
+	if engine.IsInCoroutine() {
 		return engine.WaitNextFrame()
 	} else {
 		// Fallback to a regular wait