Protocol buffer schemas shared by KBVE services, games and sites.
Last changed in19476db91on
syntax = "proto3";
package meme;
import "kbve/common.proto";
// =============================================================================
// Enums
// =============================================================================
// Content format of the meme asset
enum MemeFormat {
MEME_FORMAT_UNSPECIFIED = 0;
MEME_FORMAT_IMAGE = 1; // JPEG, PNG, WebP
MEME_FORMAT_GIF = 2; // Animated GIF
MEME_FORMAT_VIDEO = 3; // MP4, WebM
MEME_FORMAT_WEBP_ANIM = 4; // Animated WebP
}
// Moderation / lifecycle status
enum MemeStatus {
MEME_STATUS_UNSPECIFIED = 0;
MEME_STATUS_DRAFT = 1; // User-created, not yet published
MEME_STATUS_PENDING = 2; // Awaiting moderation review
MEME_STATUS_PUBLISHED = 3; // Live and visible in feed
MEME_STATUS_REJECTED = 4; // Rejected by moderation
MEME_STATUS_ARCHIVED = 5; // Soft-deleted / hidden by author
MEME_STATUS_FLAGGED = 6; // Auto-flagged by content filter
MEME_STATUS_BANNED = 7; // Hard-removed by admin
}
// Quick-tap reactions while scrolling
enum ReactionType {
REACTION_UNSPECIFIED = 0;
REACTION_LIKE = 1;
REACTION_DISLIKE = 2;
REACTION_FIRE = 3; // "this is fire"
REACTION_SKULL = 4; // "I'm dead" / hilarious
REACTION_CRY = 5; // Laughing-crying
REACTION_CAP = 6; // "cap" / disbelief
}
// Card rarity tiers for meme card battles
enum MemeRarity {
MEME_RARITY_UNSPECIFIED = 0;
MEME_RARITY_COMMON = 1;
MEME_RARITY_UNCOMMON = 2;
MEME_RARITY_RARE = 3;
MEME_RARITY_EPIC = 4;
MEME_RARITY_LEGENDARY = 5;
MEME_RARITY_MYTHIC = 6; // One-of-a-kind / event-only
}
// Card element type for battle matchups
enum MemeElement {
MEME_ELEMENT_UNSPECIFIED = 0;
MEME_ELEMENT_DANK = 1; // Classic dank memes
MEME_ELEMENT_WHOLESOME = 2; // Wholesome / feel-good
MEME_ELEMENT_CURSED = 3; // Cursed imagery
MEME_ELEMENT_DEEP_FRIED = 4; // Deep-fried / distorted
MEME_ELEMENT_SURREAL = 5; // Abstract / surreal
MEME_ELEMENT_META = 6; // Self-referential / meta
MEME_ELEMENT_EDGY = 7; // Dark humor
MEME_ELEMENT_NOSTALGIC = 8; // Retro / classic memes
}
// Card ability trigger timing
enum AbilityTrigger {
ABILITY_TRIGGER_UNSPECIFIED = 0;
ABILITY_TRIGGER_ON_PLAY = 1; // When card enters the field
ABILITY_TRIGGER_ON_ATTACK = 2; // When card attacks
ABILITY_TRIGGER_ON_DEFEND = 3; // When card is attacked
ABILITY_TRIGGER_ON_DEATH = 4; // When card is destroyed
ABILITY_TRIGGER_PASSIVE = 5; // Always active while on field
ABILITY_TRIGGER_ON_TURN_START = 6;
ABILITY_TRIGGER_ON_TURN_END = 7;
}
// Card ability effect types
enum AbilityEffect {
ABILITY_EFFECT_UNSPECIFIED = 0;
ABILITY_EFFECT_DAMAGE = 1; // Deal direct damage
ABILITY_EFFECT_HEAL = 2; // Restore HP
ABILITY_EFFECT_BUFF_ATK = 3; // Boost attack
ABILITY_EFFECT_BUFF_DEF = 4; // Boost defense
ABILITY_EFFECT_DEBUFF_ATK = 5; // Reduce enemy attack
ABILITY_EFFECT_DEBUFF_DEF = 6; // Reduce enemy defense
ABILITY_EFFECT_DRAW = 7; // Draw extra cards
ABILITY_EFFECT_STUN = 8; // Skip enemy turn
ABILITY_EFFECT_SHIELD = 9; // Absorb next hit
ABILITY_EFFECT_ELEMENT_SHIFT = 10; // Change element mid-battle
}
// Feed sort / algorithm selection
enum FeedSort {
FEED_SORT_UNSPECIFIED = 0;
FEED_SORT_HOT = 1; // Engagement-weighted recency
FEED_SORT_NEW = 2; // Chronological (newest first)
FEED_SORT_TOP = 3; // Highest reactions in time window
FEED_SORT_RANDOM = 4; // Shuffle / discovery mode
FEED_SORT_RISING = 5; // Fast-growing engagement velocity
}
// Time window for "top" feed sorting
enum FeedTimeWindow {
FEED_TIME_UNSPECIFIED = 0;
FEED_TIME_HOUR = 1;
FEED_TIME_DAY = 2;
FEED_TIME_WEEK = 3;
FEED_TIME_MONTH = 4;
FEED_TIME_ALL = 5;
}
// Report reason categories
enum ReportReason {
REPORT_REASON_UNSPECIFIED = 0;
REPORT_REASON_SPAM = 1;
REPORT_REASON_NSFW = 2;
REPORT_REASON_HATE_SPEECH = 3;
REPORT_REASON_HARASSMENT = 4;
REPORT_REASON_COPYRIGHT = 5;
REPORT_REASON_MISINFORMATION = 6;
REPORT_REASON_OTHER = 7;
}
// Battle match state
enum BattleStatus {
BATTLE_STATUS_UNSPECIFIED = 0;
BATTLE_STATUS_WAITING = 1; // Waiting for opponent
BATTLE_STATUS_IN_PROGRESS = 2;
BATTLE_STATUS_COMPLETED = 3;
BATTLE_STATUS_ABANDONED = 4;
BATTLE_STATUS_DRAW = 5;
}
// =============================================================================
// Caption - Text overlay on a meme
// =============================================================================
message MemeCaption {
string text = 1;
float position_x = 2; // 0.0–1.0 normalized X
float position_y = 3; // 0.0–1.0 normalized Y
optional float font_size = 4;
optional string font_family = 5;
optional string color = 6; // Hex color, e.g. "#FFFFFF"
optional string stroke_color = 7;
optional float stroke_width = 8;
optional float rotation = 9; // Degrees
optional string text_align = 10; // "left", "center", "right"
optional float max_width = 11; // 0.0–1.0 normalized max width for wrapping
}
// =============================================================================
// MemeTemplate - Reusable base image with defined caption slots
// =============================================================================
message TemplateCaptionSlot {
string label = 1; // e.g. "top_text", "bottom_text"
float default_x = 2; // Default normalized X position
float default_y = 3; // Default normalized Y position
optional float default_font_size = 4;
optional string placeholder = 5; // Hint text, e.g. "Top text here"
optional float max_width = 6;
optional int32 max_chars = 7; // Character limit for this slot
}
message MemeTemplate {
string id = 1; // ULID
string name = 2; // Display name, e.g. "Drake Hotline Bling"
optional string description = 3;
string image_url = 4; // Base template image
optional string thumbnail_url = 5;
int32 width = 6; // Original pixel width
int32 height = 7; // Original pixel height
repeated TemplateCaptionSlot slots = 8;
int64 usage_count = 9; // How many memes created from this template
repeated string tags = 10; // Template categories, e.g. ["reaction", "drake"]
string created_at = 11;
optional string updated_at = 12;
}
// =============================================================================
// Meme - Core entity (the card in the feed)
// =============================================================================
message Meme {
string id = 1; // ULID
string author_id = 2; // User UUID (from auth)
optional string title = 3;
optional string template_id = 4; // ULID reference to MemeTemplate (if created from one)
MemeFormat format = 5;
MemeStatus status = 6;
// Asset
string asset_url = 7; // Final rendered meme URL (CDN path)
optional string thumbnail_url = 8;
optional int32 width = 9; // Pixel width
optional int32 height = 10; // Pixel height
optional int64 file_size = 11; // Bytes
// Captions baked into this meme (for re-rendering / accessibility)
repeated MemeCaption captions = 12;
// Categorization
repeated string tags = 13;
optional string source_url = 14; // Original source attribution
optional string alt_text = 15; // Accessibility description
// Engagement counters (denormalized for feed read performance)
int64 view_count = 16;
int64 reaction_count = 17;
int64 share_count = 18;
int64 comment_count = 19;
int64 save_count = 20; // Bookmark / collection saves
// Timestamps (ISO 8601 strings)
string created_at = 21;
optional string updated_at = 22;
optional string published_at = 23;
// Card game layer (populated when meme is minted as a card)
optional MemeCardStats card = 24;
// Content hash for deduplication (perceptual hash of the image)
optional string content_hash = 25;
}
// =============================================================================
// MemeCardStats - Battle stats for the card game layer
// =============================================================================
message CardAbility {
string name = 1; // e.g. "Ratio'd", "Repost Shield"
string description = 2;
AbilityTrigger trigger = 3;
AbilityEffect effect = 4;
int32 value = 5; // Effect magnitude (damage amount, buff amount, etc.)
optional int32 cooldown = 6; // Turns before reuse (0 = every turn)
optional int32 duration = 7; // How many turns buff/debuff lasts
}
message MemeCardStats {
string meme_id = 13; // ULID FK → Meme.id (the minted meme)
MemeRarity rarity = 1;
MemeElement element = 2;
int32 attack = 3; // 0–999
int32 defense = 4; // 0–999
int32 hp = 5; // 1–9999
int32 energy_cost = 6; // Cost to play this card (0–10)
repeated CardAbility abilities = 7;
optional string flavor_text = 8; // Lore / joke text on the card
// Evolution / leveling
int32 level = 9; // 1–100, affects stat scaling
int64 xp = 10; // Experience points earned from battles
optional string evolves_from = 11; // ULID of pre-evolution meme card
optional string evolves_into = 12; // ULID of next evolution
}
// Element matchup modifier (for building the type chart)
message ElementMatchup {
MemeElement attacker = 1;
MemeElement defender = 2;
float damage_multiplier = 3; // 0.5 = resist, 1.0 = neutral, 2.0 = super effective
}
// =============================================================================
// MemeReaction - User reaction event
// =============================================================================
message MemeReaction {
string meme_id = 1; // ULID
string user_id = 2; // User UUID
ReactionType reaction = 3;
string created_at = 4;
}
// =============================================================================
// MemeComment - User comment on a meme
// =============================================================================
message MemeComment {
string id = 1; // ULID
string meme_id = 2; // ULID
string author_id = 3; // User UUID
string body = 4; // Comment text (max 500 chars)
optional string parent_id = 5; // ULID for threaded replies (null = top-level)
int64 reaction_count = 6;
int32 reply_count = 7; // Denormalized child count
string created_at = 8;
optional string updated_at = 9;
}
// =============================================================================
// MemeSave / Collections - User bookmarks and organized collections
// =============================================================================
message MemeSave {
string meme_id = 1; // ULID
string user_id = 2; // User UUID
optional string collection_id = 3; // ULID, null = default "Saved" collection
string created_at = 4;
}
message MemeCollection {
string id = 1; // ULID
string owner_id = 2; // User UUID
string name = 3; // e.g. "Favorites", "Best of 2026"
optional string description = 4;
optional string cover_meme_id = 5; // ULID of meme used as cover image
bool is_public = 6; // Visible to other users
int32 meme_count = 7; // Denormalized count
string created_at = 8;
optional string updated_at = 9;
}
// =============================================================================
// User Meme Profile - Aggregated stats for a meme.sh user
// =============================================================================
message MemeUserProfile {
string user_id = 1; // User UUID (from auth)
optional string display_name = 2;
optional string avatar_url = 3;
optional string bio = 4;
// Aggregate stats
int64 total_memes = 5; // Memes submitted
int64 total_reactions_received = 6;
int64 total_views_received = 7;
int32 follower_count = 8;
int32 following_count = 9;
// Card game stats
optional MemePlayerStats card_stats = 10;
string joined_at = 11;
optional string updated_at = 12;
}
// Card game player statistics
message MemePlayerStats {
string user_id = 9; // UUID FK → auth.users.id
int32 total_battles = 1;
int32 wins = 2;
int32 losses = 3;
int32 draws = 4;
int32 elo_rating = 5; // Matchmaking rating (default 1000)
int32 cards_owned = 6;
int32 highest_streak = 7; // Longest win streak
optional string rank_title = 8; // e.g. "Meme Lord", "Shitposter Supreme"
}
// =============================================================================
// User Follow relationship
// =============================================================================
message MemeFollow {
string follower_id = 1; // User UUID who is following
string following_id = 2; // User UUID being followed
string created_at = 3;
}
// =============================================================================
// Card Deck - A player's battle deck
// =============================================================================
// A card slot within a deck (maps 1:1 to meme.meme_deck_cards join table)
message DeckCard {
string card_id = 1; // ULID FK → Meme.id (with card stats)
optional int32 position = 2; // Ordering position within the deck
}
message MemeDeck {
string id = 1; // ULID
string owner_id = 2; // User UUID
string name = 3; // Deck name, e.g. "Cursed Rush"
repeated DeckCard cards = 4; // Cards in this deck (replaces flat card_ids)
bool is_active = 5; // Currently selected deck for matchmaking
string created_at = 6;
optional string updated_at = 7;
}
// =============================================================================
// Battle - A card game match between two players
// =============================================================================
// A single action within a battle turn
message BattleAction {
int32 turn = 1;
string player_id = 2; // User UUID of acting player
string card_id = 3; // ULID of card used
optional string target_card_id = 4; // ULID of target card (if applicable)
optional string ability_name = 5; // Ability used (if not basic attack)
int32 damage_dealt = 6;
int32 healing_done = 7;
optional string effect_applied = 8; // Description of any status effect
}
message BattleResult {
string battle_id = 1; // ULID
string player_a_id = 2; // User UUID
string player_b_id = 3; // User UUID
BattleStatus status = 4;
optional string winner_id = 5; // User UUID of winner (null on draw/abandoned)
int32 total_turns = 6;
repeated BattleAction actions = 7; // Full action log for replays
int32 elo_delta_a = 8; // Rating change for player A
int32 elo_delta_b = 9; // Rating change for player B
string created_at = 10;
optional string completed_at = 11;
}
// =============================================================================
// Moderation
// =============================================================================
message MemeReport {
string id = 1; // ULID
string meme_id = 2; // ULID
string reporter_id = 3; // User UUID
ReportReason reason = 4;
optional string detail = 5; // Free-text elaboration
bool resolved = 6;
optional string resolved_by = 7; // Admin user UUID
optional string resolution_note = 8;
string created_at = 9;
optional string resolved_at = 10;
}
// =============================================================================
// Feed - Infinite scroll cursor pagination
// =============================================================================
message FeedRequest {
int32 limit = 1; // Items per page (1–50)
optional string cursor = 2; // Opaque pagination cursor (ULID-based)
FeedSort sort = 3;
optional FeedTimeWindow time_window = 4; // Required when sort = TOP
optional string tag = 5; // Filter by tag
optional string author_id = 6; // Filter by author
optional MemeElement element = 7; // Filter by card element
optional bool cards_only = 8; // Only show memes with card stats
}
message FeedResponse {
repeated Meme memes = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// =============================================================================
// Requests / Responses
// =============================================================================
// --- Submit a meme ---
message SubmitMemeRequest {
optional string title = 1;
optional string template_id = 2; // If created from a template
MemeFormat format = 3;
string asset_url = 4;
repeated MemeCaption captions = 5;
repeated string tags = 6;
optional string source_url = 7;
optional string alt_text = 8;
}
message SubmitMemeResponse {
kbve.common.Result result = 1;
optional Meme meme = 2;
}
// --- Get single meme by ID ---
message GetMemeRequest {
string id = 1; // ULID
}
message GetMemeResponse {
bool found = 1;
optional Meme meme = 2;
}
// --- Update meme ---
message UpdateMemeRequest {
string id = 1;
optional string title = 2;
repeated string tags = 3;
optional string alt_text = 4;
optional MemeStatus status = 5; // Author can archive their own memes
}
message UpdateMemeResponse {
kbve.common.Result result = 1;
optional Meme meme = 2;
}
// --- Delete meme ---
message DeleteMemeRequest {
string id = 1;
}
message DeleteMemeResponse {
kbve.common.Result result = 1;
}
// --- React ---
message ReactRequest {
string meme_id = 1;
ReactionType reaction = 2;
}
message ReactResponse {
kbve.common.Result result = 1;
}
// --- Comment ---
message AddCommentRequest {
string meme_id = 1;
string body = 2;
optional string parent_id = 3; // For threaded replies
}
message AddCommentResponse {
kbve.common.Result result = 1;
optional MemeComment comment = 2;
}
message ListCommentsRequest {
string meme_id = 1;
int32 limit = 2; // 1–100
optional string cursor = 3;
optional string parent_id = 4; // Null = top-level, set = replies to this comment
}
message ListCommentsResponse {
repeated MemeComment comments = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// --- Save / Bookmark ---
message SaveMemeRequest {
string meme_id = 1;
optional string collection_id = 2; // Null = default collection
}
message SaveMemeResponse {
kbve.common.Result result = 1;
}
message UnsaveMemeRequest {
string meme_id = 1;
optional string collection_id = 2;
}
message UnsaveMemeResponse {
kbve.common.Result result = 1;
}
// --- Collections ---
message CreateCollectionRequest {
string name = 1;
optional string description = 2;
bool is_public = 3;
}
message CreateCollectionResponse {
kbve.common.Result result = 1;
optional MemeCollection collection = 2;
}
message ListCollectionsRequest {
string owner_id = 1; // User UUID
int32 limit = 2;
optional string cursor = 3;
}
message ListCollectionsResponse {
repeated MemeCollection collections = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
message GetCollectionMemesRequest {
string collection_id = 1;
int32 limit = 2;
optional string cursor = 3;
}
message GetCollectionMemesResponse {
repeated Meme memes = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// --- Templates ---
message GetTemplateRequest {
string id = 1;
}
message GetTemplateResponse {
bool found = 1;
optional MemeTemplate template = 2;
}
message ListTemplatesRequest {
int32 limit = 1;
optional string cursor = 2;
optional string search = 3; // Fuzzy search on template name
}
message ListTemplatesResponse {
repeated MemeTemplate templates = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// --- User Profile ---
message GetMemeProfileRequest {
string user_id = 1;
}
message GetMemeProfileResponse {
bool found = 1;
optional MemeUserProfile profile = 2;
}
// --- Follow ---
message FollowRequest {
string target_user_id = 1;
}
message FollowResponse {
kbve.common.Result result = 1;
}
message UnfollowRequest {
string target_user_id = 1;
}
message UnfollowResponse {
kbve.common.Result result = 1;
}
message ListFollowersRequest {
string user_id = 1;
int32 limit = 2;
optional string cursor = 3;
}
message ListFollowersResponse {
repeated MemeUserProfile followers = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
message ListFollowingRequest {
string user_id = 1;
int32 limit = 2;
optional string cursor = 3;
}
message ListFollowingResponse {
repeated MemeUserProfile following = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// --- Report ---
message ReportMemeRequest {
string meme_id = 1;
ReportReason reason = 2;
optional string detail = 3;
}
message ReportMemeResponse {
kbve.common.Result result = 1;
}
// --- Mint a meme as a battle card ---
message MintCardRequest {
string meme_id = 1; // Existing meme to mint
}
message MintCardResponse {
kbve.common.Result result = 1;
optional MemeCardStats card = 2; // Generated stats based on meme engagement
}
// --- Deck management ---
message CreateDeckRequest {
string name = 1;
repeated string card_ids = 2;
}
message CreateDeckResponse {
kbve.common.Result result = 1;
optional MemeDeck deck = 2;
}
message UpdateDeckRequest {
string deck_id = 1;
optional string name = 2;
repeated string card_ids = 3;
optional bool is_active = 4;
}
message UpdateDeckResponse {
kbve.common.Result result = 1;
optional MemeDeck deck = 2;
}
message ListDecksRequest {
string owner_id = 1;
}
message ListDecksResponse {
repeated MemeDeck decks = 1;
}
// --- Battle ---
message StartBattleRequest {
string deck_id = 1; // Player's active deck
}
message StartBattleResponse {
kbve.common.Result result = 1;
optional string battle_id = 2;
optional BattleStatus status = 3;
}
message GetBattleRequest {
string battle_id = 1;
}
message GetBattleResponse {
bool found = 1;
optional BattleResult battle = 2;
}
message ListBattleHistoryRequest {
string user_id = 1;
int32 limit = 2;
optional string cursor = 3;
}
message ListBattleHistoryResponse {
repeated BattleResult battles = 1;
optional string next_cursor = 2;
bool has_more = 3;
}
// =============================================================================
// Services
// =============================================================================
// Core meme feed and content management
service MemeService {
// Feed
rpc GetFeed (FeedRequest) returns (FeedResponse);
rpc GetMeme (GetMemeRequest) returns (GetMemeResponse);
// CRUD
rpc SubmitMeme (SubmitMemeRequest) returns (SubmitMemeResponse);
rpc UpdateMeme (UpdateMemeRequest) returns (UpdateMemeResponse);
rpc DeleteMeme (DeleteMemeRequest) returns (DeleteMemeResponse);
// Engagement
rpc React (ReactRequest) returns (ReactResponse);
rpc AddComment (AddCommentRequest) returns (AddCommentResponse);
rpc ListComments (ListCommentsRequest) returns (ListCommentsResponse);
// Bookmarks & Collections
rpc SaveMeme (SaveMemeRequest) returns (SaveMemeResponse);
rpc UnsaveMeme (UnsaveMemeRequest) returns (UnsaveMemeResponse);
rpc CreateCollection (CreateCollectionRequest) returns (CreateCollectionResponse);
rpc ListCollections (ListCollectionsRequest) returns (ListCollectionsResponse);
rpc GetCollectionMemes (GetCollectionMemesRequest) returns (GetCollectionMemesResponse);
// Moderation
rpc ReportMeme (ReportMemeRequest) returns (ReportMemeResponse);
}
// Template library for meme creation
service MemeTemplateService {
rpc GetTemplate (GetTemplateRequest) returns (GetTemplateResponse);
rpc ListTemplates (ListTemplatesRequest) returns (ListTemplatesResponse);
}
// User social layer
service MemeSocialService {
rpc GetProfile (GetMemeProfileRequest) returns (GetMemeProfileResponse);
rpc Follow (FollowRequest) returns (FollowResponse);
rpc Unfollow (UnfollowRequest) returns (UnfollowResponse);
rpc ListFollowers (ListFollowersRequest) returns (ListFollowersResponse);
rpc ListFollowing (ListFollowingRequest) returns (ListFollowingResponse);
}
// Card game: minting, deck building, battles
service MemeCardService {
rpc MintCard (MintCardRequest) returns (MintCardResponse);
rpc CreateDeck (CreateDeckRequest) returns (CreateDeckResponse);
rpc UpdateDeck (UpdateDeckRequest) returns (UpdateDeckResponse);
rpc ListDecks (ListDecksRequest) returns (ListDecksResponse);
rpc StartBattle (StartBattleRequest) returns (StartBattleResponse);
rpc GetBattle (GetBattleRequest) returns (GetBattleResponse);
rpc ListBattleHistory (ListBattleHistoryRequest) returns (ListBattleHistoryResponse);
}