samp/
lib.rs

1//! Rust toolkit for developing SA-MP plugins and native Open Multiplayer components.
2//!
3//! # Workspace structure
4//!
5//! - `samp` — main crate; re-exports SDK + codegen and exposes the API the plugin uses.
6//! - `samp-codegen` — proc macros (`#[native]`, `initialize_plugin!`,
7//!   `#[derive(SampPlugin)]`) that generate FFI entry points and argument parsing.
8//! - `samp-sdk` — low-level bindings for the AMX VM (SA-MP) and for the component
9//!   ABI (Open Multiplayer).
10//!
11//! # Minimal `Cargo.toml` setup
12//!
13//! ```toml
14//! [lib]
15//! crate-type = ["cdylib"]
16//!
17//! [dependencies]
18//! samp = { git = "https://github.com/NullSablex/rust-samp" }
19//! ```
20//!
21//! # Plugin example
22//!
23//! ```rust,ignore
24//! use samp::prelude::*;
25//! use samp::{native, initialize_plugin, SampPlugin};
26//!
27//! #[derive(SampPlugin, Default)]
28//! struct MyPlugin;
29//!
30//! impl MyPlugin {
31//!     #[native(name = "Greet")]
32//!     fn greet(&mut self, _amx: &Amx, name: &AmxString) -> AmxResult<bool> {
33//!         if name.starts_with("Admin") {
34//!             println!("[VIP] Welcome, {}!", &**name);
35//!         } else {
36//!             println!("Hello, {}!", &**name);
37//!         }
38//!         Ok(true)
39//!     }
40//! }
41//!
42//! // Short form — default constructor via Default::default().
43//! initialize_plugin!(
44//!     type: MyPlugin,
45//!     natives: [MyPlugin::greet],
46//! );
47//!
48//! // Full form when there is setup in the constructor (logger, tick, etc):
49//! // initialize_plugin!(
50//! //     natives: [MyPlugin::greet],
51//! //     {
52//! //         samp::plugin::enable_tick();
53//! //         return MyPlugin;
54//! //     }
55//! // );
56//! ```
57
58pub mod amx;
59#[doc(hidden)]
60pub mod interlayer;
61pub mod logger;
62#[cfg(not(feature = "samp-only"))]
63pub(crate) mod macros;
64pub mod plugin;
65pub(crate) mod runtime;
66
67pub use samp_codegen::{initialize_plugin, native};
68
69// Re-export so the generated macro does not leak the `log` dep into the user's Cargo.toml.
70#[doc(hidden)]
71pub use log;
72
73/// Derive macro that generates an empty `impl SampPlugin for T {}` for structs
74/// that do not need to customize any trait method. For structs with logic in
75/// `on_load`/`on_tick`/etc, declare `impl SampPlugin for T { ... }`
76/// manually instead of using the derive.
77pub use samp_codegen::SampPlugin;
78pub use samp_sdk::exec_public;
79pub use samp_sdk::{args, cell, consts, error, exports, raw};
80
81#[cfg(feature = "encoding")]
82pub use samp_sdk::encoding;
83
84#[cfg(not(feature = "samp-only"))]
85pub use samp_sdk::omp;
86
87pub mod prelude {
88    //! Most commonly used imports in plugins.
89    pub use crate::amx::{Amx, AmxExt};
90    pub use crate::cell::{AmxCell, AmxString, Buffer, CellConvert, Ref, UnsizedBuffer};
91    pub use crate::error::AmxResult;
92    pub use crate::plugin::SampPlugin;
93}
94
95/// Installs the SDK logger with defaults derived from the caller's
96/// `Cargo.toml`. Writes to `logs/{CARGO_PKG_NAME}.log` with size-based
97/// rotation (50 MB × 5 archives) and forwards every line to the server's
98/// own log prefixed with `[CARGO_PKG_NAME]`.
99///
100/// Returns `Result<(), samp::logger::InstallError>` — the most common
101/// failures are "already installed" (a second call in the same process)
102/// and "I/O" (the log directory could not be created).
103///
104/// # Example
105/// ```rust,ignore
106/// fn on_load(&mut self) {
107///     let _ = samp::enable_logger!();
108///     log::info!("ready");
109/// }
110/// ```
111#[macro_export]
112macro_rules! enable_logger {
113    () => {
114        $crate::enable_logger_with!($crate::logger::LoggerConfig::new(env!("CARGO_PKG_NAME")))
115    };
116}
117
118/// Installs the SDK logger with an explicit [`LoggerConfig`].
119///
120/// The macro still seeds the banner metadata from the caller's
121/// `CARGO_PKG_*` values before delegating to [`logger::install`], so the
122/// startup banner reports the user's plugin even when every other field
123/// is overridden.
124///
125/// [`LoggerConfig`]: crate::logger::LoggerConfig
126/// [`logger::install`]: crate::logger::install
127#[macro_export]
128macro_rules! enable_logger_with {
129    ($cfg:expr) => {{
130        $crate::logger::__set_banner_metadata($crate::logger::BannerMetadata::new(
131            env!("CARGO_PKG_NAME"),
132            env!("CARGO_PKG_VERSION"),
133            env!("CARGO_PKG_AUTHORS"),
134            env!("CARGO_PKG_REPOSITORY"),
135        ));
136        $crate::logger::install($cfg)
137    }};
138}
samp/lib.rs

samp/
lib.rs
