windows-development-sandbox 1.20.0 → 1.23.1

package/sandbox/addons/perplexity-mcp/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "sandbox-addon-perplexity-mcp",
+  "private": true,
+  "dependencies": {
+    "@perplexity-ai/mcp-server": "1.3.0"
+  }
+}

package/sandbox/scripts/add-firewall-port.ps1

@@ -1,7 +1,9 @@
 #Requires -Version 5.1
 # Opens an inbound TCP/UDP port in the sandbox's own firewall (sbx-fivem serve: 30120 and txAdmin's 40120), so the PC
-# can reach a server running in the sandbox. Not available yet: changes nothing.
-# Exit code: 0 = done, 1 = not available yet.
+# can reach a server running in the sandbox. Only from the sandbox's own subnet (the PC's Hyper-V network), never from
+# anywhere else. Running it again replaces the rule. Uses netsh: the NetSecurity cmdlets fail in Windows Sandbox
+# ("Invalid class"), like guest/network/firewall.ts.
+# Exit code: 0 = done, 1 = the rule could not be added.
 param(
     [Parameter(Mandatory = $true)][ValidateRange(1, 65535)][int]$Port,
     [ValidateSet('TCP', 'UDP', 'Both')][string]$Protocol = 'Both',
@@ -9,5 +11,17 @@ param(
 )
 $ErrorActionPreference = 'Stop'
 
-Write-Output ('add-firewall-port: not available yet (port ' + $Port + ', ' + $Name + ')')
-exit 1
+$netsh = Join-Path $env:SystemRoot 'System32\netsh.exe'
+$protocols = if ($Protocol -eq 'Both') { @('TCP', 'UDP') } else { @($Protocol) }
+foreach ($p in $protocols) {
+    $rule = 'AgentSandbox ' + $Name + ' (' + $p + ' ' + $Port + ')'
+    & $netsh advfirewall firewall delete rule ('name=' + $rule) | Out-Null
+    $out = & $netsh advfirewall firewall add rule ('name=' + $rule) dir=in action=allow enable=yes profile=any `
+        ('protocol=' + $p) ('localport=' + $Port) remoteip=LocalSubnet
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error ('Could not open ' + $p + ' ' + $Port + ': ' + ($out -join ' ')) -ErrorAction Continue
+        exit 1
+    }
+    Write-Output ('Opened ' + $p + ' ' + $Port + ' for ' + $Name + ' (from the PC only)')
+}
+exit 0

package/sandbox/scripts/set-machine-environment.ps1

@@ -34,24 +34,39 @@ foreach ($folder in @($settings.create)) {
     if ($folder) { New-Item -ItemType Directory -Force -Path $folder | Out-Null }
 }
 
-foreach ($variable in $settings.vars.PSObject.Properties) {
-    if ($additive -and [Environment]::GetEnvironmentVariable($variable.Name, 'Machine')) { continue }
-    [Environment]::SetEnvironmentVariable($variable.Name, [string]$variable.Value, 'Machine')
-}
+# The boot, its background re-persist and the daemon can all run this script: the read-modify-write of the machine
+# Environment key happens under one named mutex (an abandoned mutex, from a killed script, is ours to take).
+$mutex = New-Object System.Threading.Mutex($false, 'Global\AgentSandboxMachineEnv')
+$owned = $false
+try {
+    try {
+        $owned = $mutex.WaitOne(60000)
+    } catch [System.Threading.AbandonedMutexException] {
+        $owned = $true
+    }
+    if (-not $owned) { throw 'Another script has held the machine environment lock for over 60 seconds' }
+    foreach ($variable in $settings.vars.PSObject.Properties) {
+        if ($additive -and [Environment]::GetEnvironmentVariable($variable.Name, 'Machine')) { continue }
+        [Environment]::SetEnvironmentVariable($variable.Name, [string]$variable.Value, 'Machine')
+    }
 
-if ($null -ne $settings.path) {
-    [Environment]::SetEnvironmentVariable('Path', (Join-Folders ([string]$settings.path -split ';')), 'Machine')
-}
+    if ($null -ne $settings.path) {
+        [Environment]::SetEnvironmentVariable('Path', (Join-Folders ([string]$settings.path -split ';')), 'Machine')
+    }
 
-if ($settings.add) {
-    $current = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';'
-    $known = @{}
-    foreach ($folder in $current) { $known[(Get-Key $folder)] = $true }
-    $missing = @($settings.add | Where-Object { -not $known.ContainsKey((Get-Key $_)) })
-    if ($missing.Count) {
-        $combined = if ($additive) { $current + $missing } else { $missing + $current }
-        [Environment]::SetEnvironmentVariable('Path', (Join-Folders $combined), 'Machine')
+    if ($settings.add) {
+        $current = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';'
+        $known = @{}
+        foreach ($folder in $current) { $known[(Get-Key $folder)] = $true }
+        $missing = @($settings.add | Where-Object { -not $known.ContainsKey((Get-Key $_)) })
+        if ($missing.Count) {
+            $combined = if ($additive) { $current + $missing } else { $missing + $current }
+            [Environment]::SetEnvironmentVariable('Path', (Join-Folders $combined), 'Machine')
+        }
     }
+} finally {
+    if ($owned) { $mutex.ReleaseMutex() }
+    $mutex.Dispose()
 }
 
 try {

package/sandbox/templates/fivem/README.txt

@@ -1,2 +1,6 @@
-Templates for `sbx-fivem new <resource> --lua | --js | --ts | --cs` (a server.cfg and one folder per language).
-Not available yet.
+Templates for sbx-fivem (docs/fivem.md):
+- server.cfg: what `sbx-fivem init` writes into a new server folder. It holds no key: sbx-fivem serve reads the
+  Cfx.re key from a cfg on the sandbox's own disk (+exec) before this one.
+- lua, js, ts, cs: one folder per language for `sbx-fivem new <resource> --lua | --js | --ts | --cs`.
+Placeholders: {{name}} (the resource), {{namespace}} (its name as a C# namespace), {{game}} (gta5 or rdr3) and
+{{gameLines}} (the manifest's game lines).

package/sandbox/templates/fivem/cs/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <!-- FiveM loads client C# from *.net.dll built for .NET Framework 4.5.2 (Mono in the game). -->
+  <PropertyGroup>
+    <TargetFramework>net452</TargetFramework>
+    <AssemblyName>{{name}}.Client</AssemblyName>
+    <RootNamespace>{{namespace}}.Client</RootNamespace>
+    <TargetName>$(AssemblyName).net</TargetName>
+    <DebugType>embedded</DebugType>
+    <LangVersion>latest</LangVersion>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="CitizenFX.Core.Client" Version="1.0.*" ExcludeAssets="runtime" />
+    <PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" PrivateAssets="all" />
+  </ItemGroup>
+</Project>

package/sandbox/templates/fivem/cs/Client/ClientMain.cs

@@ -0,0 +1,20 @@
+using System;
+using System.Collections.Generic;
+using CitizenFX.Core;
+using static CitizenFX.Core.Native.API;
+
+namespace {{namespace}}.Client
+{
+    /// <summary>{{name}}, client side: the /{{name}} command asks the server to say hello.</summary>
+    public class ClientMain : BaseScript
+    {
+        public ClientMain()
+        {
+            RegisterCommand("{{name}}", new Action<int, List<object>, string>((source, args, raw) =>
+            {
+                TriggerServerEvent("{{name}}:hello");
+            }), false);
+            EventHandlers["{{name}}:reply"] += new Action<string>(message => Debug.WriteLine(message));
+        }
+    }
+}

package/sandbox/templates/fivem/cs/Server/Server.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <!-- FXServer loads server C# from *.net.dll built for .NET Standard 2.0. -->
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <AssemblyName>{{name}}.Server</AssemblyName>
+    <RootNamespace>{{namespace}}.Server</RootNamespace>
+    <TargetName>$(AssemblyName).net</TargetName>
+    <DebugType>embedded</DebugType>
+    <LangVersion>latest</LangVersion>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="CitizenFX.Core.Server" Version="1.0.*" ExcludeAssets="runtime" />
+  </ItemGroup>
+</Project>

package/sandbox/templates/fivem/cs/Server/ServerMain.cs

@@ -0,0 +1,20 @@
+using System;
+using CitizenFX.Core;
+
+namespace {{namespace}}.Server
+{
+    /// <summary>{{name}}, server side: answers the client's hello.</summary>
+    public class ServerMain : BaseScript
+    {
+        public ServerMain()
+        {
+            EventHandlers["{{name}}:hello"] += new Action<Player>(OnHello);
+        }
+
+        private void OnHello([FromSource] Player player)
+        {
+            Debug.WriteLine(player.Name + " said hello");
+            player.TriggerEvent("{{name}}:reply", "Hello from the server");
+        }
+    }
+}

package/sandbox/templates/fivem/cs/fxmanifest.lua

@@ -0,0 +1,11 @@
+fx_version 'cerulean'
+{{gameLines}}
+
+name '{{name}}'
+description 'Made with sbx-fivem new (C#: dotnet publish -c Release in Client and Server)'
+version '0.1.0'
+
+file 'Client/bin/Release/**/publish/*.dll'
+
+client_script 'Client/bin/Release/**/publish/*.net.dll'
+server_script 'Server/bin/Release/**/publish/*.net.dll'

package/sandbox/templates/fivem/js/client.js

@@ -0,0 +1,12 @@
+// {{name}}, client side: the /{{name}} command asks the server to say hello.
+RegisterCommand(
+  '{{name}}',
+  () => {
+    emitNet('{{name}}:hello');
+  },
+  false,
+);
+
+onNet('{{name}}:reply', (message) => {
+  console.log(message);
+});

package/sandbox/templates/fivem/js/fxmanifest.lua

@@ -0,0 +1,9 @@
+fx_version 'cerulean'
+{{gameLines}}
+
+name '{{name}}'
+description 'Made with sbx-fivem new'
+version '0.1.0'
+
+client_script 'client.js'
+server_script 'server.js'

package/sandbox/templates/fivem/js/server.js

@@ -0,0 +1,6 @@
+// {{name}}, server side: answers the client's hello.
+onNet('{{name}}:hello', () => {
+  const player = source;
+  console.log(GetPlayerName(player) + ' said hello');
+  emitNet('{{name}}:reply', player, 'Hello from the server');
+});

package/sandbox/templates/fivem/lua/client.lua

@@ -0,0 +1,8 @@
+-- {{name}}, client side: the /{{name}} command asks the server to say hello.
+RegisterCommand('{{name}}', function()
+  TriggerServerEvent('{{name}}:hello')
+end, false)
+
+RegisterNetEvent('{{name}}:reply', function(message)
+  print(message)
+end)

package/sandbox/templates/fivem/lua/fxmanifest.lua

@@ -0,0 +1,10 @@
+fx_version 'cerulean'
+{{gameLines}}
+lua54 'yes'
+
+name '{{name}}'
+description 'Made with sbx-fivem new'
+version '0.1.0'
+
+client_script 'client.lua'
+server_script 'server.lua'

package/sandbox/templates/fivem/lua/server.lua

@@ -0,0 +1,6 @@
+-- {{name}}, server side: answers the client's hello.
+RegisterNetEvent('{{name}}:hello', function()
+  local player = source
+  print(('%s said hello'):format(GetPlayerName(player)))
+  TriggerClientEvent('{{name}}:reply', player, 'Hello from the server')
+end)

package/sandbox/templates/fivem/server.cfg

@@ -0,0 +1,37 @@
+# A FiveM / RedM development server, made by `sbx-fivem init`. Start it with `sbx-fivem serve`.
+#
+# No keys in this file: sbx-fivem serve runs FXServer with `+exec <a cfg on the sandbox's own disk>` first, which
+# sets sv_licenseKey (and steam_webApiKey) from your saved Cfx.re key (sandbox account login cfx). Keep it that way:
+# this file is part of your project.
+
+endpoint_add_tcp "0.0.0.0:30120"
+endpoint_add_udp "0.0.0.0:30120"
+
+sv_hostname "{{name}} (development)"
+sets sv_projectName "{{name}}"
+sets sv_projectDesc "A development server in a Windows Sandbox"
+sv_maxclients 8
+sv_scriptHookAllowed 0
+
+# Keep it off the public server list (you connect by address).
+sv_master1 ""
+
+# The standard resources (chat, spawnmanager, sessionmanager ...) come from cfx-server-data:
+#   git clone https://github.com/citizenfx/cfx-server-data
+# then copy its resources folder to resources\[cfx-default] and remove the # below.
+# ensure mapmanager
+# ensure chat
+# ensure spawnmanager
+# ensure sessionmanager
+# ensure basic-gamemode
+# ensure hardcap
+
+# oxmysql: sbx-fivem serve sets mysql_connection_string to the sandbox's MariaDB (databases.mysql) when it runs;
+# a set mysql_connection_string line here wins over it.
+# ensure oxmysql
+
+# Admins: add your identifier (the console shows it when you join) to use admin commands.
+# add_principal identifier.fivem:1234567 group.admin
+add_ace group.admin command allow
+
+# Your resources: sbx-fivem new <name> adds its ensure line below.

package/sandbox/templates/fivem/ts/build.js

@@ -0,0 +1,17 @@
+// Bundles src/client and src/server into dist/client.js and dist/server.js, the files fxmanifest.lua loads.
+// `node build.js --watch` rebuilds on every change (then `restart {{name}}` in the server console).
+const esbuild = require('esbuild');
+
+const watch = process.argv.includes('--watch');
+const builds = [
+  { entryPoints: ['src/client/client.ts'], outfile: 'dist/client.js', platform: 'browser', target: 'es2020' },
+  { entryPoints: ['src/server/server.ts'], outfile: 'dist/server.js', platform: 'node', target: 'node16' },
+];
+
+(async () => {
+  for (const b of builds) {
+    const options = { ...b, bundle: true, format: 'iife', logLevel: 'info' };
+    if (watch) await (await esbuild.context(options)).watch();
+    else await esbuild.build(options);
+  }
+})().catch(() => process.exit(1));

package/sandbox/templates/fivem/ts/fxmanifest.lua

@@ -0,0 +1,9 @@
+fx_version 'cerulean'
+{{gameLines}}
+
+name '{{name}}'
+description 'Made with sbx-fivem new (TypeScript: npm install, then npm run build)'
+version '0.1.0'
+
+client_script 'dist/client.js'
+server_script 'dist/server.js'

package/sandbox/templates/fivem/ts/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "node build.js",
+    "watch": "node build.js --watch",
+    "check": "tsc -p src/client --noEmit && tsc -p src/server --noEmit"
+  },
+  "devDependencies": {
+    "@citizenfx/client": "2.0.38182-1",
+    "@citizenfx/server": "2.0.38182-1",
+    "esbuild": "^0.28.0",
+    "typescript": "~5.9.0"
+  }
+}

package/sandbox/templates/fivem/ts/src/client/client.ts

@@ -0,0 +1,12 @@
+// {{name}}, client side: the /{{name}} command asks the server to say hello.
+RegisterCommand(
+  '{{name}}',
+  () => {
+    emitNet('{{name}}:hello');
+  },
+  false,
+);
+
+onNet('{{name}}:reply', (message: string) => {
+  console.log(message);
+});

package/sandbox/templates/fivem/ts/src/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020"],
+    "types": ["@citizenfx/client"]
+  },
+  "include": ["./**/*.ts"]
+}

package/sandbox/templates/fivem/ts/src/server/server.ts

@@ -0,0 +1,6 @@
+// {{name}}, server side: answers the client's hello.
+onNet('{{name}}:hello', () => {
+  const player = String(source);
+  console.log(GetPlayerName(player) + ' said hello');
+  emitNet('{{name}}:reply', player, 'Hello from the server');
+});

package/sandbox/templates/fivem/ts/src/server/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020"],
+    "types": ["@citizenfx/server"]
+  },
+  "include": ["./**/*.ts"]
+}