A cross-platform X-Plane plugin demonstrating OpenAL sound playback functionality. This plugin serves as a practical example for developers learning to create audio-enabled X-Plane plugins.
You don't need to compile this plugin yourself! This repository uses GitHub Actions to automatically compile binaries for all supported platforms whenever code changes are made.
- Latest Release: Go to the Releases page to download the latest stable version
- Development Builds: Check the Actions tab for the latest development builds from recent commits
Each release includes:
win.xpl
- Windows (64-bit)mac.xpl
- macOS Universal (Intel + Apple Silicon)lin.xpl
- Linux (64-bit)OpenALSharedExample.tar.gz
- All platforms bundled together
The GitHub Actions workflow automatically:
- โ Builds for Windows, macOS, and Linux on every commit
- โ Runs comprehensive cross-platform tests
- โ
Creates releases when the
VERSION
file is updated - โ Packages all platforms into convenient downloads
- โ Generates installation instructions
Simply update the VERSION
file and push to trigger a new release!
- Cross-platform compatibility: Windows, macOS (Intel & Apple Silicon), Linux
- OpenAL integration: Demonstrates proper OpenAL context management in X-Plane
- Automatic sound playback: Plays sound when aircraft is loaded
- Pitch shifting: Each playback increases pitch slightly for demonstration
- Proper plugin lifecycle: Shows correct initialization and cleanup procedures
- Download the appropriate
.xpl
file for your platform from the Releases page - Create the plugin directory:
X-Plane/Resources/plugins/OpenALSharedExample/
- Copy the
.xpl
file to this directory - Add a
sound.wav
file to the same directory (any WAV file will work) - Restart X-Plane
If you need to modify the code or prefer to compile yourself:
- CMake 3.16 or later
- C++ compiler with C++17 support
- OpenAL development libraries (Linux only - Windows/macOS include OpenAL)
# Clone the repository
git clone https://github.com/6639835/xplane-plugin-example
cd xplane-plugin-example
# Build for your platform
python build_all.py
# Or build with cleanup
python build_all.py clean
# Windows
python build_all.py --platform windows
# macOS
python build_all.py --platform mac
# Linux
python build_all.py --platform linux
The compiled plugin will be in the build/
directory.
- Load X-Plane with the plugin installed
- Load any aircraft - the plugin will automatically play a sound
- Check Log.txt for plugin status messages and OpenAL information
- Each aircraft load will play the sound at a progressively higher pitch
โโโ src/ # Source code
โ โโโ OpenAL-Shared-Example.cpp
โโโ SDK/ # X-Plane SDK (included)
โโโ build/ # Build output directory
โโโ .github/workflows/ # GitHub Actions CI/CD
โโโ CMakeLists.txt # CMake configuration
โโโ build_all.py # Cross-platform build script
โโโ VERSION # Version file (triggers releases)
โโโ README.md # This file
- Fork the repository
- Make your changes to the source code
- Test locally using
python build_all.py
- Push your changes - GitHub Actions will automatically build and test
- Create a pull request
- Update the
VERSION
file with the new version number (e.g.,1.1.0
) - Commit and push the change to the main branch
- GitHub Actions will automatically:
- Build all platforms
- Create a git tag
- Generate a GitHub release
- Upload all binaries
The repository includes a comprehensive CI/CD pipeline that:
- Builds the plugin for Windows, macOS, and Linux
- Uploads build artifacts for download
- Runs cross-platform compatibility tests
- Automatically creates git tags
- Generates GitHub releases with changelogs
- Packages all platform binaries
- Creates installation instructions
- Matrix builds across all platforms simultaneously
- Artifact retention for 30-90 days
- Automatic dependency installation (CMake, OpenAL, etc.)
- Universal macOS binaries (Intel + Apple Silicon)
- Comprehensive error handling and logging
- Creates its own OpenAL device and context
- Properly shares OpenAL with X-Plane and other plugins
- Demonstrates correct context switching
- Includes comprehensive error checking
- Uses XPLM SDK version 4.1.0 (backwards compatible)
- Proper plugin lifecycle management
- Cross-platform file path handling
- Deferred initialization pattern
- CMake-based with platform-specific configurations
- Symbol export control for proper plugin loading
- Compiler optimization and security flags
- Framework linking on macOS, static linking on other platforms
- Check X-Plane's
Log.txt
for error messages - Ensure the correct
.xpl
file for your platform - Verify the plugin directory structure
- Make sure
sound.wav
exists in the plugin directory
- Check that OpenAL is working on your system
- Verify the
sound.wav
file is a valid WAV file - Check X-Plane's audio settings
- Look for OpenAL error messages in
Log.txt
- Use pre-compiled binaries from GitHub releases instead
- Check that all dependencies are installed
- Ensure CMake 3.16+ is available
- Verify the X-Plane SDK is present in the
SDK/
directory
This project is licensed under the terms specified in the LICENSE
file.
Contributions are welcome! The GitHub Actions workflow ensures that all contributions are automatically tested across platforms.
- Fork the repository
- Create a feature branch
- Make your changes
- Push and create a pull request
- GitHub Actions will automatically build and test your changes
๐ก Remember: You can rely on GitHub Actions to compile files for all platforms automatically. No need for manual compilation unless you're actively developing!