@smoud/scripts
Version:
Powerful build tool for HTML5 games, designed to streamline development, optimization, and packaging for multiple platforms, including web browsers, game portals, social media, mobile, and Web3
352 lines (256 loc) • 10.9 kB
Markdown
# @smoud/scripts
[](https://www.npmjs.com/package/@smoud/scripts)
[](https://www.npmjs.com/package/@smoud/scripts)
[](https://deepscan.io/dashboard#view=project&tid=19616&pid=29227&bid=939281)
[](https://github.com/smoudjs/scripts/blob/master/LICENSE)
**The Ultimate Build Tool for HTML5 Games**
`@smoud/scripts` is a powerful build tool for HTML5 games, designed to streamline development, optimization, and packaging for multiple platforms, including web browsers, game portals (CrazyGames, Poki, ...), social media (Facebook, Snapchat, TikTok, ...), mobile, and Web3/blockchain platforms. This tool provides a one-command solution to handle platform-specific requirements, asset optimization, and build automation.
## Features
- 🚀 **One-Command Build Process** – Easily generate builds for different platforms.
- ⚡ **Automatic Optimizations** – Includes minification, tree-shaking, and dead code elimination.
- 🎯 **Pre-configured for Major Platforms** – Works out of the box with **web browsers, game portals, social media platforms, mobile platforms, and Web3/blockchain platforms**.
- 🛠️ **Customizable** – Extend the default build pipeline as needed.
## Installation
```bash
npm install --save-dev @smoud/scripts
```
## Quick Start
1. Install the package
2. Create a basic project structure:
```
your-game/
├── src/
│ ├── index.html
│ └── index.ts
├── package.json
└── build.json (optional)
```
3. Add scripts to your package.json:
```json
{
"scripts": {
"dev": "smoud-scripts dev",
"build": "smoud-scripts build"
}
}
```
4. Start development:
```bash
npm run dev
```
5. Build for a specific platform:
```bash
npm run build browser
```
## CLI Arguments
| Option | Description | Default | Example |
| ------------------------- | ---------------------------------------- | ------------------ | -------------------------------------- |
| **Platform** | Target platform | `browser` | `poki` |
| `--name` | Project name | from package.json | `--name MyGame` |
| `--version` | Project version | from package.json | `--version 1.0.0` |
| `--out-dir` | Output directory for build files | `build/{platform}` | `--out-dir build/{version}/{platform}` |
| `--static-dir` | Source directory of static build files | `static` | `--static-dir public` |
| `--build-config` | Path to build.json configuration file | `build.json` | `--build-config custom.json` |
| `--ts-config` | Path to tsconfig.json configuration file | `tsconfig.json` | `--ts-config tsconfig.prod.json` |
| `--js-config` | Path to jsconfig.json configuration file | `jsconfig.json` | `--js-config jsconfig.prod.json` |
| `--port` | Development server port number | `3000` | `--port 8080` |
| `--open` | Open browser automatically | `false` | `--open` |
| `--dev` | Enable development mode | `true` | `--dev false` |
| `--skip-recommended-meta` | Skip recommended meta tags injection | `false` | `--skip-recommended-meta` |
| `--debugger` | URL of debugger script to inject | - | `--debugger https://...` |
#### Target Platform
Specify the target platform directly as a command argument:
```bash
smoud-scripts build poki
```
#### Supported Platforms
- **Web Browsers**
- `browser` - Standard web browser
- **Web-Based Game Portals**
- `crazygames` - CrazyGames
- `poki` - Poki
- `kongregate` - Kongregate
- `newgrounds` - Newgrounds
- `y8` - Y8
- `gamedistribution` - GameDistribution
- `miniclip` - Miniclip
- **Indie-Focused & Pay-What-You-Want Platforms**
- `itch` - itch.io
- `gamejolt` - Game Jolt
- `simmer` - Simmer.io
- **Mobile Platforms (via WebView or PWA)**
- `googleplay` - Google Play
- `appstore` - App Store
- `galaxystore` - Galaxy Store
- `amazonappstore` - Amazon Appstore
- **Social Media & Messenger Games**
- `facebook` - Facebook
- `snapchat` - Snapchat
- `wechat` - WeChat
- `tiktok` - TikTok
- `telegram` - Telegram
- **Web3 & Blockchain-Based Platforms**
- `sandbox` - The Sandbox
- `opgames` - OP Games
- `immutablex` - Immutable X
#### Supported Languages
- `auto`, `en`, `es`, `zh`, `hi`, `ar`, `fr`, `de`, `ja`, `pt`, `it`, `ko`, `tr`, `nl`, `sv`, `pl`, `uk`, `id`, `vi`
## Build Configuration (build.json)
The `build.json` file allows you to customize build options. Here's the format:
```json
{
"outDir": "dist/{platform}",
"name": "MyGame",
"version": "1.2.0",
"language": "en"
}
```
All fields are optional and will use the default values if not specified.
## Output directory name template
The `outDir` template (specified with `--out-dir` option) supports the following variables:
- `{name}` - Project name
- `{version}` - Project version
- `{language}` - Language code
- `{platform}` - Target platform
- `{date}` - Current date
- `{hash}` - Unique build identifier
Example: `--out-dir "build/{name}_{version}_{platform}"`
## Meta Tags
Unless `--skip-recommended-meta` is provided, the following recommended for mobile platforms meta tags are automatically injected:
```html
<meta name="HandheldFriendly" content="True" />
<meta name="cleartype" http-equiv="cleartype" content="on" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="mobile-web-app-capable" content="yes" />
<meta http-equiv="X-UA-Compatible" content="IE=10" />
```
## Examples
### Development
Start development server:
```bash
smoud-scripts dev --port 3000 --open
```
### Building
Build for browser:
```bash
npx smoud-scripts build browser
```
```bash
npm run build browser
```
Build for Poki:
```bash
npx smoud-scripts build poki
```
```bash
npm run build poki
```
Build for Facebook:
```bash
npx smoud-scripts build facebook
```
```bash
npm run build facebook
```
## API Reference
The package provides a programmatic API for integration into your build tools:
### Default Options
```javascript
const options = {
// CLI options
name: '', // Project name (default from package.json)
version: '', // Project version (default from package.json)
outDir: 'build/{platform}', // Output directory for build files
staticDir: 'static', // Source directory of static build files
buildConfig: 'build.json', // Path to build.json configuration file
tsConfig: 'tsconfig.json', // For TypeScript projects, path to tsconfig.json file
jsConfig: 'jsconfig.json', // For JavaScript projects, path to jsconfig.json file
port: 3000, // Development server port number
open: false, // Whether to open browser automatically
platform: 'browser', // Target platform
language: 'auto', // Target language
dev: undefined, // Development mode flag
skipRecommendedMeta: undefined, // Skip recommended meta tags injection
debugger: undefined, // URL of debugger script to inject
// Defines options (automatically generated from CLI options)
defines: {
__DEV__: false, // Development mode flag
PLATFORM: '...', // Current platform identifier
LANGUAGE: '...' // Current language code
}
};
```
### Configuration
```javascript
const { options, mergeOptions, parseArgvOptions } = require('@smoud/scripts');
// Merge custom options with defaults
const customOptions = mergeOptions(options, {
outDir: 'custom-dist',
platform: 'poki'
});
// Parse CLI arguments
const newOptions = parseArgvOptions([
{
name: 'custom-option',
hasValue: true,
defaultValue: 'default'
}
]);
// Change options
newOptions.platform = 'crazygames';
newOptions.version = '1.0.5';
// Change defines options
newOptions.defines = {
CUSTOM_DEFINE: JSON.stringify('custom value'),
__DEV__: JSON.stringify(false)
};
// Merge new options with defaults
const finalOptions = mergeOptions(options, newOptions);
```
### Webpack Configuration
```javascript
const { makeWebpackDevConfig, makeWebpackBuildConfig } = require('@smoud/scripts');
const { webpackCommonConfig } = require('@smoud/scripts');
const { merge } = require('webpack-merge');
// Create development configuration
const devConfig = makeWebpackDevConfig(customOptions);
// Create production configuration
const buildConfig = makeWebpackBuildConfig();
// Create production configuration with custom definitions
const buildConfig2 = makeWebpackBuildConfig(customOptions, customDefinitions);
// Create production configuration with custom definitions and custom webpack config to merge
const buildConfig3 = makeWebpackBuildConfig(customOptions, customDefinitions, customWebpackConfig);
// Create your own webpack config, based on webpackCommonConfig
const customConfig = merge(webpackCommonConfig, {
// ...
});
```
### Development Server
```javascript
const { runDev } = require('@smoud/scripts');
// Start development server with custom config
runDev(webpackDevConfig);
// Start development server with default config
runDev();
// Start development server with custom definitions
runDev(null, null, customDefines);
```
### Production Build
```javascript
const { runBuild } = require('@smoud/scripts');
// Run production build with custom config
runBuild(webpackBuildConfig);
// Run production build with default config
runBuild();
// Run production build with custom options
runBuild(null, customOptions);
```
### Plugins
The package includes several webpack plugins for platform integration:
```javascript
const { DebuggerInjectionPlugin } = require('@smoud/scripts');
// Custom debugger integration
new DebuggerInjectionPlugin('http://debugger-url');
```
## Issues
Report issues at [GitHub Issues](https://github.com/smoudjs/scripts/issues)