@l8b/player

LootiScript API Binding - Farcaster player context and information for Mini Apps.

Note: This package is used as an API binding for LootiScript in the l8b engine. It provides access to Farcaster player information when running in a Farcaster Mini App environment.

API Reference

Properties

// Player FID (Farcaster ID)
local fid = player.fid

// Player username
local username = player.username

// Player display name
local displayName = player.displayName

// Player profile picture URL
local pfpUrl = player.pfpUrl

Methods

player.getFid()

Get the player's Farcaster ID.

local fid = player.getFid()
// Returns: number (FID, or 0 if not in Mini App)

player.getUsername()

Get the player's username.

local username = player.getUsername()
// Returns: string | undefined

player.getDisplayName()

Get the player's display name.

local displayName = player.getDisplayName()
// Returns: string | undefined

player.getPfpUrl()

Get the player's profile picture URL.

local pfpUrl = player.getPfpUrl()
// Returns: string | undefined

player.getContext()

Get the full player context object.

local context = player.getContext()
// Returns: PlayerContext object with:
//   - fid: number
//   - username?: string
//   - displayName?: string
//   - pfpUrl?: string
//   - location?: Location object
//   - client: Client object

The context includes location information about how the Mini App was opened:

• cast_embed - Opened from a cast embed
• cast_share - Opened from a cast share
• notification - Opened from a notification
• launcher - Opened from the launcher
• channel - Opened from a channel
• open_miniapp - Opened via open_miniapp action

player.isInMiniApp()

Check if the game is running in a Farcaster Mini App environment.

if player.isInMiniApp() == 1 then
  // Running in Mini App
else
  // Running in standalone mode
end

Share Extensions

Share extensions allow your Mini App to receive shared casts from the Farcaster share sheet.

player.isFromShare()

Check if the Mini App was opened from a share extension.

if player.isFromShare() == 1 then
  // App was opened via share extension
  local cast = player.getSharedCast()
  if cast then
    print("Shared cast from: " .. cast.author.username)
    print("Cast text: " .. cast.text)
  end
end

player.getSharedCast()

Get the shared cast if the app was opened from a share extension.

local cast = player.getSharedCast()
if cast then
  local author = cast.author
  print("Author: " .. (author.displayName or author.username))
  print("Cast hash: " .. cast.hash)
  print("Cast text: " .. cast.text)
end

Returns: Cast object with author, hash, text, timestamp, etc., or undefined if not opened from share.

player.isFromNotification()

Check if the Mini App was opened from a notification.

if player.isFromNotification() == 1 then
  local notification = player.getNotification()
  if notification then
    print("Notification: " .. notification.title)
    print("Body: " .. notification.body)
  end
end

player.getNotification()

Get the notification if the app was opened from a notification.

local notification = player.getNotification()
if notification then
  print("Notification ID: " .. notification.notificationId)
  print("Title: " .. notification.title)
  print("Body: " .. notification.body)
end

Returns: Notification object with notificationId, title, body, or undefined if not opened from notification.

Example Usage

function init()
  // Check if in Mini App
  if player.isInMiniApp() == 1 then
    print("Welcome, " .. (player.getDisplayName() or player.getUsername() or "Player"))
    print("FID: " .. player.getFid())
  else
    print("Running in standalone mode")
  end
end

function update()
  // Access player properties
  local fid = player.fid
  local username = player.username
  
  // Handle share extensions
  if player.isFromShare() == 1 then
    local cast = player.getSharedCast()
    if cast then
      print("Shared cast from: " .. cast.author.username)
      print("Cast: " .. cast.text)
      // Handle shared cast logic
    end
  end
  
  // Handle notifications
  if player.isFromNotification() == 1 then
    local notification = player.getNotification()
    if notification then
      print("Opened from notification: " .. notification.title)
      // Handle notification-specific logic
    end
  end
  
  // Get full context for advanced usage
  local context = player.getContext()
  if context.location then
    if context.location.type == "cast_embed" then
      // Handle cast embed context
      local cast = context.location.cast
      if cast then
        print("Opened from cast: " .. cast.text)
      end
    end
  end
end

function draw()
  // Display player info
  screen.setFont("BitCell")
  screen.setColor("#FFFFFF")
  
  if player.isInMiniApp() == 1 then
    screen.drawText("Player: " .. (player.getDisplayName() or player.getUsername() or "Unknown"), 10, 10, 12)
    screen.drawText("FID: " .. player.getFid(), 10, 30, 12)
    
    // Display profile picture if available
    if player.pfpUrl then
      // Note: You would need to load the image first using Assets
      // local pfp = Assets.loadImage(player.pfpUrl)
      // screen.drawImage(pfp, 10, 50, 64, 64)
    end
  else
    screen.drawText("Standalone Mode", 10, 10, 12)
  end
end

Context Structure

The getContext() method returns a PlayerContext object with the following structure:

{
  fid: number,                    // Farcaster ID
  username?: string,               // Username
  displayName?: string,            // Display name
  pfpUrl?: string,                 // Profile picture URL
  location?: {                     // How the Mini App was opened
    type: "cast_embed" | "cast_share" | "notification" | "launcher" | "channel" | "open_miniapp",
    cast?: {                       // If opened from a cast
      author: {
        fid: number,
        username?: string,
        displayName?: string,
        pfpUrl?: string
      },
      hash: string,
      text: string,
      timestamp?: number,
      parentHash?: string,
      parentFid?: number
    },
    notification?: {               // If opened from a notification
      notificationId: string,
      title: string,
      body: string
    },
    channel?: {                    // If opened from a channel
      key: string,
      name: string,
      imageUrl?: string
    },
    referrerDomain?: string        // If opened via open_miniapp
  },
  client: {
    platformType?: "web" | "mobile",
    clientFid: number,
    added: boolean
  }
}

Notes

• When not running in a Farcaster Mini App environment, fid will be 0 and other properties will be undefined
• The isInMiniApp() method can be used to check if player context is available
• All methods are synchronous except for internal initialization, which happens automatically
• The context is cached after first access for performance